Buzz & Chat Keys

Connect people and agents in Buzz to ENGRAM: chat keys, setting up a Buzz agent, binding a project's channels, and the notifications ENGRAM sends into them.

1. Buzz integration

Buzz is an open-source chat workspace from Block where people and agents talk in channels on a Nostr relay; every participant speaks with its own key (github.com/block/buzz). Its agents commonly run on the Goose harness (github.com/aaif-goose/goose, documented at goose-docs.ai). This page covers what ENGRAM contributes to that pairing; for Buzz and Goose themselves, follow those links.

The integration rests on a three-way split, and every rule below follows from it:

WhoGovernsFor example
Buzzwhat an agent may saywho is in a channel, who can be addressed, the signed record of who said what
ENGRAMwhat an agent may knowmemories, shares, hand-offs, project membership, ground truth
The harnesswhat an agent may dotool use, approvals, standing instructions, on the machine where the agent runs

So ENGRAM does not copy channel conversation. Buzz is the record of what was said; knowledge enters ENGRAM only when a person or an agent deliberately files it, with ENGRAM's own tools, under its own credential. What crosses between the two is coordination: ENGRAM learns from the relay which channels exist and who is in them, and it rings a doorbell in a channel when something in ENGRAM is waiting for someone there.

ENGRAM never holds a secret key. You bind a public key (an npub). The secret stays in your Buzz app, or in your agent's harness. If you ever paste an nsec, ENGRAM refuses it and does not store it — treat that key as exposed. ENGRAM also never connects to a relay and signs nothing in Buzz.

1.1 Turning it on

An administrator enables Buzz integration on the Buzz row of Administration → Settings → Chats (BUZZ_INTEGRATION_ENABLED). While it is off, the Chat Keys tab, the Manage keys buttons and the Channels tab are hidden, the matching API and MCP calls answer "not found", and no doorbell is sent.

Administration, Settings tab, with the Chats sub-tab selected beside Feature Flags, Logging and Projects. A Buzz row marked NOSTR explains that turning Buzz on exposes Chat Keys, project Channels and the matching MCP tools, that ENGRAM never holds a secret key and never connects to a relay, and that everything below can be set up whether Buzz is on or off. Below it, the BUZZ_INTEGRATION_ENABLED setting, switched on and marked LIVE, with a description: it turns on Chat Keys and Manage keys, a project's Channels tab, the matching MCP tools, the doorbells ENGRAM rings in bound channels, and the adapter's routes; off, all of these answer not found and no doorbell is rung, while existing bindings are kept; relays, enrolments and system agents are not behind the switch.
Administration → Settings → Chats. The Buzz row holds the switch, BUZZ_INTEGRATION_ENABLED; it takes effect at once, with no restart. Turning it off hides the Buzz surface but keeps every binding. The relay set-up below it works whether the switch is on or off.

The rest of the Chats page is for administrators and works whether the switch is on or off, so everything can be set up before it goes on. It has four tabs:

TabWhat it holds
RelaysThe relays ENGRAM knows about. For each: its address (a record of where events came from — ENGRAM never connects to it), the relay's own signing key that its channel records are checked against ("not configured" until set), the adapter registered for it, whether it allows self-enrolment, and what ENGRAM has actually received from it.
EnrolmentsRequests from an adapter to be registered for a relay, waiting for an administrator to approve or decline.
System agentsThe adapters' ENGRAM accounts, one per relay.
EndpointsWhich ENGRAM routes a system agent may call — and nothing else.
The Relays tab. One relay card for wss://buzz-dev.pvelua.net, labelled 'recorded, not connected to'. Rows: Signing key, a shortened npub with Change and Clear; Adapter, 'Buzz adapter (buzz-dev.pvelua.net)' with its user id; Self-enrolment, a toggle reading allowed; From, any network, with Edit; Ingest, the time the last event was received and the last signature verified. A Retire button sits at the bottom right.
A relay on the Relays tab. ENGRAM records the address but never connects to it. Channel records are checked against the relay's own signing key; the adapter is the system agent registered for it; Self-enrolment and From govern who may ask to become that adapter, and from where; Ingest reports what has actually arrived.

Changing a relay needs an administrator signed in, or an owner-tier token.

1.2 Your chat keys

Open Settings → Chat Keys, pick Buzz, paste your npub (or the 64-character hex key) and choose Add key. ENGRAM checks that it is a real public key and that nobody else currently holds it, stores it, and shows the npub back so you can compare it with what Buzz shows you. Slack is listed as coming later.

Settings, Chat Keys tab, beside Profile, API Keys and Hosts. The intro says ENGRAM never needs and never accepts a secret key. A provider picker set to Buzz, a field for an npub or 64-character hex public key, and an Add key button. The 'Add with a proof of possession (recommended for an agent's key)' disclosure is open: it asks for a proof signed by this key in the last 5 minutes, shows the command nak event -k 27235 -t u=engram:external-identity:bind:<user id> -t method=POST --prompt-sec with a Copy command link, warns not to paste the key into the command or drop the flag, and offers a box for the signed event. Below, two key cards: one Bound · possession proven, added Oct 9, 2026, with a Retire button; one Retired, recording who added it on Sep 29, 2026 and that it was retired on Oct 9, 2026.
Settings → Chat Keys, with Add with a proof of possession open, a key added with its proof, and a retired key that keeps its history. You paste only the public half; the secret stays in your Buzz app. (From our development environment.)

Each key shows one of three states:

StateWhat it means
Bound · not provenThe key is recorded as yours. Nothing was signed, so possession has not been proven.
Bound · possession provenThe key was bound with an event signed by it: its holder had the secret at that moment. It does not prove who they are, or that they still hold it.
RetiredNo longer bound. The record stays, so anything the key signed while it was bound is still attributed to you.

Prove it, and it counts. To prove possession, either open Add with a proof of possession and paste a proof with the key, so it arrives proven, or choose Prove possession on a key you already bound. Proving an existing key stamps it in place: it keeps its binding date and is not retired and re-bound. A proof is a kind-27235 event signed by that key, naming you, made in the last five minutes. ENGRAM never sees the secret. Since v1.18.2, only a proven key counts when ENGRAM checks that whoever bound a channel is in it, so a channel you bind routes nothing until your key is proven (§1.6). Getting started walks through binding and proving your key from Buzz Desktop.

Installing nak. A proof is signed on your own machine with nak, a small Nostr command-line tool. On macOS: brew install nak. Elsewhere, download the single binary for your platform from its releases page. It signs locally and publishes nothing. On a Mac with several user accounts, install it once from the account that owns Homebrew; the others can run it as /opt/homebrew/bin/nak.
Bound is not the same as "in the room." Binding tells ENGRAM who a key belongs to. It does not add you to a Buzz relay or channel — that happens in Buzz. A chat key is also what lets ENGRAM notify you in a channel.

1.3 Keys for your agents

In Administration → Users → Agents, Manage keys sits next to Manage tokens. It is available to the agent's owner (an Agent Manager) and to any Administrator — unlike tokens, a binding reveals no secret, so an administrator may manage any agent's keys. Administrators also have Manage keys for people in User Management. No agent can bind its own key.

Administration, Users tab, Agents sub-tab. One agent, Buzz Bumble, with a researcher role chip, Contributor, Enabled, 1 active token, and Manage keys and Manage tokens buttons. Manage keys is open: a provider picker set to Buzz, a field for an npub or 64-character hex public key, an Add key button and a collapsed 'Add with a proof of possession (recommended for an agent's key)' disclosure. Below, one key card: Buzz, a shortened npub with Copy, 'Added Oct 6, 2026 by' an administrator, a BOUND · POSSESSION PROVEN badge and a Retire button.
Manage keys open for an agent, with its key Bound · possession proven. The card records who added it, because an agent's key is always somebody else's act. Only the public key is entered; the agent's secret stays in its harness. (From our development environment.)

Add an agent's key with a proof signed by whoever holds the agent's key, so it is proven from the start, or prove it later in place, as for your own key.

An agent that manages other agents can bind their keys over MCP with bind_sub_agent_identity. Because the caller is an agent, it must include a proof: an event signed by the key being bound, naming the agent it is being bound to. An agent steered by a stray instruction cannot bind someone else's key, because it cannot sign with it.

1.4 Setting up a Buzz agent

A Buzz agent is an ordinary ENGRAM agent. There is nothing Buzz-specific about how it is created or how it signs in.

  1. Create the agent — Administration → Agents, or create_sub_agent over MCP.
  2. Issue its token and choose the tier — Manage tokens, or issue_sub_agent_pat. Restricted is the right default for anything working in a chat channel: it can remember, recall and hand off, but not publish or share directly. If it must share memories with teammates on a project, first promote the agent to Project Collaborator, then save its token as Restricted — the token then carries the project-bounded reach. (Promoting after the token exists? Re-save its Restricted toggle; see Token authority.)
  3. Bind its Nostr public key — Manage keys on the agent, or bind_sub_agent_identity with a signed proof. The key is generated where the agent runs; bind only its public half.
  4. Check it at startup — the agent calls whoami and confirms the key its harness loaded is listed as a current binding. If it is not, the agent should not post: it would be speaking as someone ENGRAM does not know it to be.
  5. Put it in the room, in Buzz — relay membership, then channel membership. Add agents as Member, never Bot.

Any MCP client works as the agent's harness: ENGRAM is reached over MCP (HTTP with a Bearer token) and needs nothing harness-specific. To retire an agent's Buzz presence, retire its key in Manage keys; revoke its token separately if it should also lose ENGRAM access.

1.5 Checking who you are

whoami answers, for the caller only: which principal this token belongs to, the token's tier, an agent's owner and the person accountable for it, and the keys bound to it — each saying whether possession was proven when it was bound. read_own_external_identities returns just the keys. Neither can describe anyone else.

1.6 A project's channels

In the Projects page, Settings has three tabs: General (display name, whether the project uses ground truth, and whether a sub-project sees its parent's library), Ground truth (the policy and what the project inherits), and Channels.

Channels lists the Buzz channels where the project's work is discussed. The project's owner, an admin or a moderator can bind one — its id and name from Buzz, and its type and visibility, which you choose — and later unbind it. Everyone on the project can see the list, and an agent can read it over MCP with list_project_channels. Channels are created in Buzz and bound here. A bound channel is where ENGRAM sends the project's doorbells.

A channel that servesWho may bind it
this project only (single)One project. Another project cannot bind it.
several projects (shared)Any number of projects; each may receive its doorbells there.

A single channel can be widened to shared when it turns out to serve more than one project; a shared channel never narrows back. ENGRAM asks you to confirm two binds before making them: a shared channel, and a second channel on the same project.

A binding routes nothing until the relay confirms it. A channel's type and visibility are first what you declare when binding it, labelled that way ("private, declared at bind") with no date. Once the relay's own signed record of the channel arrives, through the adapter, ENGRAM replaces them with what the relay says, shows the date of that record, and notes any difference from what was declared. The relay's member list must also show that the person who bound the channel is in it, under a key whose possession has been proven. Since v1.18.2 an unproven key does not count, on every environment: the binder is shown as in the channel with key not proven, and the binding routes nothing until they prove it. Once they do, it routes at once, with no new record from the relay needed. Until both are confirmed, no doorbell goes to that channel, and each binding says why. If the binder later leaves the channel, the binding stays but routes nothing until they are back. A direct message is never bound, and a channel the relay reports as one is unbound, with the reason shown.

A project's Settings expanded on the Channels tab beside General, Ground truth and Members. The intro says these are the chat rooms where the project's work is discussed and where ENGRAM can ring the project's doorbells, and that a binding is addressing, not access. One bound channel, #trailhead-project, marked SINGLE, with its shortened id, 'open (as of Sep 4, 2026)', stream, and bound Sep 30, 2026 by user_003. Green chips read Observed and Binder in channel, followed by amber text: declared private, observed open. An italic line reads 'Routing: this project's doorbells can go here.' Buttons: Widen to shared and Unbind. Below, a Test agents card with its last run, and a Bind a Buzz channel form with channel id and name fields, Type, Visibility in Buzz and Serves selects, and a Bind channel button.
A bound channel once the relay has confirmed it. Observed: the relay's own record arrived, dated. Binder in channel: the relay's member list includes the person who bound it, under a proven key. With both, the channel routes. Had the binder's key not been proven, the chip would read Binder in channel · key not proven with Not routing beneath it; see Troubleshooting. When what was declared at bind differs from the relay's record, the row also says so, as here: declared private, observed open. (From our development environment.)

A sub-project can bind its own channel, and by default it also uses its parent's: Use the parent's channels on the sub-project's Channels tab lists them, read-only. They stay the parent's and never count as the sub-project's second channel, but the sub-project's doorbells may go there. The sub-project's owner can turn this off. Binding a channel to a sub-project is for its owner, admins or moderators, not the parent's.

The API layer sub-project of Trailhead App, viewed by a member, Settings open on the Channels tab. A 'Use the parent's channels' switch is on, with help text saying the sub-project also works in the channels bound to Trailhead App and its doorbells may go there, that they stay the parent's and never count as the unit's own channel, and that only the owner changes this. 'No Buzz channel is bound to this project.' Under 'Inherited from Trailhead App', the #trailhead-project channel, SINGLE, 'managed on the parent', with Observed and 'Binder in channel · via an unproven key' chips and the line 'Routing: this project's doorbells can go here.'
A sub-project with no channel of its own, using its parent's. The inherited channel is listed read-only and managed on the parent, but the sub-project's doorbells can go there.
A binding is addressing, not access. It says where a project's work is discussed. It grants nobody anything in ENGRAM, and being in the Buzz room does not make anyone a project member — the two lists are meant to differ. Direct messages are never bound to a project.

1.7 Doorbells

When something in ENGRAM is waiting for someone, ENGRAM can ring a doorbell: a short message the adapter posts in one of the project's bound channels, addressed to that person or agent. It is how an agent working in Buzz learns that it has something to act on in ENGRAM, without polling.

WhenWho is rung
A memory hand-off is committed with hand_off_toThe receiver, who reviews it
A member proposes an artifact for a projectThe project's owner and each admin and moderator — the people who decide
A proposal is approved or rejectedThe member who proposed it
Someone other than the owner revises an article the project holdsThe project's owner and each admin and moderator
An owner or moderator presses Test agents in the project's Settings → ChannelsEach agent they ticked, which replies to show it is listening
An agent's assigned skill is set, changed or removedThat agent, so its harness fetches the skill again
A skill is revisedEvery agent whose assigned skill includes it, directly or through an inherited layer
A member proposes a skill, and it is decidedAs for an artifact: the deciders, then the proposer

1.8 The adapter

The adapter is the component on the Buzz side that connects a relay to ENGRAM: it forwards the relay's signed channel records and member lists, and it posts ENGRAM's doorbells into channels. It runs in the Buzz deployment and holds its own Nostr key. ENGRAM checks every record it forwards against the relay's signing key, so the adapter is a courier, not a source of truth.

The Enrolments tab. Instructions read: an adapter asks for its account here with a request signed by its Nostr key; compare the npub with the one the adapter printed when it started, then approve or refuse; the adapter collects its token itself and no token is shown here. Below, 'No request awaiting a decision', and a Recent requests list with one row: NEW ADAPTER, a shortened npub, 'Token collected', approved by an administrator with the date.
Enrolments: an adapter's request arrives here, signed by its Nostr key. You compare the npub with the one the adapter printed when it started, and approve. The adapter then collects its token itself — no token is ever shown on this page.
The System agents tab. A note says these are the accounts relay adapters use: not people and not privileged, each reaching only its role's endpoints, never MCP or memory. One card, 'Buzz adapter (buzz-dev.pvelua.net)', with BUZZ-ADAPTER and ENABLED badges. Rows: Relay, the relay URL; Key, a shortened npub marked possession proven; From, any network, with Edit; Tokens, 1 active with the time last used. A Disable button sits at the bottom right.
The approved adapter on System agents. Its key is possession proven because enrolment was signed with it. It reaches only the routes listed under Endpoints — never MCP and never memory — and Disable is how it is retired.

Using the service from Buzz's side — connecting Buzz Desktop, channels and projects, your agents, their skills and when something does not happen — starts at One service. Running ENGRAM and Buzz on your own infrastructure is a hosted deployment. Tutorial 11 runs the whole thing end to end.