A proposal, a decision and a hand-off

A hands-on ENGRAM walkthrough · October 11, 2026

In Tutorial 10, ENGRAM held a proposal and decided who could read it, but woke nobody: the proposing agent had to announce it on the channel itself. Here ENGRAM rings the doorbell. We bind a Buzz channel to a project, follow four signals from ENGRAM into the room, and then check what the room still cannot reach.
Runnable on the hosted service. The Buzz integration has been on since 19 October 2026 (What's New), so every step here can be run against the hosted ENGRAM.

1. Why this tutorial exists

Tutorials 9 and 10 ran two agents across a Buzz channel and drew a line through the middle of it: the channel carries signal, ENGRAM carries substance. Two jobs on that line were still left to people. Nothing in ENGRAM told anyone that something was waiting for them — list_inbox is a poll, and an agent that never asks never finds out. And the join between an agent's Buzz key and its ENGRAM identity was a proof-of-concept script that nothing checked.

v1.18 closes both. ENGRAM now knows each principal's chat key, and when something is waiting for a decision it emits a signal. A small service, the adapter, turns that signal into an @-mention in the channel bound to the project — a doorbell. Each doorbell is tailored to whoever receives it: a person gets a one-line label and a link, and an agent also gets an embedded JSON line naming the tools that close the item. ENGRAM still reads nothing in the room, and holds no chat key of its own.

A doorbell is easy to see and easy to over-credit. It tells someone that something is waiting. It does not carry the thing, it grants nothing, and it cannot make an agent act. Each part below shows a doorbell arriving, and says what to check when one does not.

This is the most hands-on tutorial in the series: you run every step yourself, with one agent. Read Buzz & Chat Keys first if you have not. This tutorial uses its vocabulary and does not re-explain it.

The run was made on our DEV environment against ENGRAM v1.18.2, with a new project and a new private channel. Every timing below was measured on that run.

2. What you'll build

   ENGRAM  ── signal ──►  the adapter  ── doorbell ──►  your Buzz channel
     ▲                        │                                │
     │                        └── fetches the room's own record ──┘
     │
 you and your agent, over MCP          the adapter is the only part that dials out

One project you own, one agent that is a member of it, and one channel bound to it. By the end you will have seen all four signals the integration emits:

SignalRung byWho it reaches
channel.boundbinding a channel to a projectthe adapter, which fetches the room's own record
proposal.waitingthe agent proposing an artifact into your projectyou
proposal.decidedyou approving itthe agent
recap.waitingthe agent handing off what it learnedyou

Just as much the point, you will confirm what does not happen: nothing said in the channel reaches the knowledge base, and nothing done in the channel changes what the agent may do.

It takes about 45 minutes, of which 10 is provisioning.

Who's who

The ids appear in the screenshots. They are DEV ids.

NameRoleENGRAM userIn Buzz
Igor Polyakovthe lead, owner of the Tutorial 11 projectuser_003Igor P
Buzz Fizz (agent)the agent, a member of the projectuser_067Engram Fizz
Jonny Googlea second person, in Part 7 only: added without a chat key to test that case, then given a key, bound and provenuser_001—
the adapterENGRAM's system agent, which posts doorbellsa system agentENGRAM

The agent goes by two names: Buzz Fizz in ENGRAM and Engram Fizz as its Buzz profile. Both are correct. The adapter posts in the channel as ENGRAM, which is the name every doorbell in the screenshots carries.

Why the parts are in this order

A doorbell needs three things before it can ring:

  1. whoever it is for, person or agent, has a chat key ENGRAM can address (Part 1, then Part 2 for the agent);
  2. whoever it is for can be mentioned in the room, and an agent's harness lets ENGRAM's messages through (Part 2);
  3. the project has a room to ring in (Part 3).

Parts 4 to 6 are the three doorbells that matter day to day: a proposal, a decision and a hand-off. Part 7 checks that the room reached nothing it should not.

3. Prerequisites

RequirementNotes
Tutorials 9 and 10the channel versus the knowledge base, project membership, proposals and hand-offs. None of it is re-taught
ENGRAM v1.18.2+, with Buzz enabledyour Settings has a Chat Keys tab
The Buzz serviceGET https://engram-buzz.pvelua.net/version returns a release
The adapter, enrolled and approvedAdministration → Settings → Chats → System agents lists it, last used within the last minute
Buzz Desktop, signed inyou can post in a channel
An agent you can run on Gooserunning your own agent on Goose is part of a hosted deployment
An administratorto add the agent's key to the relay roster and to approve the adapter. If you run the service yourself, that is you
Get the roles right before Part 1: you own the project, and the agent is a member of it. That is what makes Part 4 a proposal. An owner adding its own artifact decides nothing, so nothing is waiting and no doorbell rings. Swap the roles and Parts 4 and 5 produce nothing at all.

4. Part 1 — Your own chat key

A doorbell is addressed to a chat key. Until you have one, ENGRAM has nothing to address, and it says so: the waiting item reads Buzz: not signalled — no Chat Key.

Binding your key takes two moves:

  1. In Buzz Desktop, copy your public key (hex).
  2. In ENGRAM, open Settings → Chat Keys → Add key, paste it and save.
An agent checks its key over MCP. whoami lists the keys bound to the caller under external_identities, and read_own_external_identities returns them. Part 2 binds the agent's key; this is how the agent itself confirms it.

The key now reads Bound · not proven. ENGRAM knows it is yours because you said so; nothing has shown that you hold the secret. So prove it: click Prove possession, sign a kind-27235 event with that key, and paste the JSON.

nak event -k 27235 -t u=engram:external-identity:bind:<your user id> -t method=POST --prompt-sec

The full version of this step is in Getting started with Buzz. Two things from it matter here:

ENGRAM Settings, Chat Keys tab. One Buzz key with a shortened npub, a Copy link and the date it was added, under a green badge reading BOUND · POSSESSION PROVEN, with a Retire button. Above it, the field for adding another key and a disclosure for adding a key together with a proof of possession.
A chat key after the proof: Bound · possession proven. The Chat Keys panel in ENGRAM's settings. Hovering the badge says what it means — the key's holder had the secret when it was bound. Without the proof the key reads Bound · not proven, and Part 3 is where that difference stops being cosmetic.
Why the proof is not optional here. In Part 3 you bind a channel to a project, which makes you that binding's binder. An unproven binder's binding routes nothing — the channel panel says so. Skip the proof and every later part is correct, and no doorbell ever arrives.

5. Part 2 — Making an agent addressable

An agent is addressable when three separate things are true. None implies another, and each one fails quietly on its own.

a. It exists in ENGRAM, with its own credential. Create the agent and issue it a restricted PAT. Never share yours: the whole provenance story rests on the agent acting as itself.

b. It has a Nostr key, and that key is on the relay roster. Generate the key and keep the secret with the agent. An administrator adds the public key:

buzz-admin add-member --pubkey <hex> --role member

c. It is a member of the channel, with the Member role. Relay membership and channel membership are two different grants. A key on the roster but not in the channel cannot be mentioned in it, and nothing reports that — not the sender, not the recipient, not the relay. What matters is the role, not the client you add it from: on our run we added the agent from the command line.

Then give it a name, so the channel shows a name rather than 64 hex characters:

buzz users set-profile --name "<Agent name>" --about "<one line: what it is, and that it is an agent>"

Finally, bind the agent's key in ENGRAM under Administration → Users → Agents → Manage keys, with a proof — Part 1 again, with the agent's user id. No agent binds its own key. The binding is something its owner does for it: an Administrator can manage keys for any agent, and an Agent Manager only for the agents it owns.

The fourth thing, and the one people miss

If the agent is to act on the doorbells ENGRAM sends it, its harness must accept messages from the adapter. A harness decides for itself whose messages are worth a turn, and the adapter is not someone it has met.

On Goose that is the agent's allowlist (who may wake an agent): add the adapter's public key alongside whoever else may address it. Skip this and everything still looks right — the doorbell is posted, correctly addressed, with its chip — and the agent never sees it. A dropped message logs nothing, so it reads as an agent being slow rather than an agent being deaf. On our run the harness dropped two doorbells this way. Once the adapter was allowed, the agent woke within 3 seconds.

The widening is safe in a way that adding another agent is not. The adapter has no model and reads no channel, so it cannot answer and cannot appear in a loop. It does have a cost: every doorbell is a turn, including the ones the agent reads and discards. Allow it for agents meant to act on ENGRAM; leave it off for agents that only talk to people.

Check it before relying on it

Post @<Agent name> ping in the channel and confirm the stored event carries a p tag:

buzz messages get --channel <channel id> --limit 3      # expect ["p","<agent hex>"]

The agent should answer; ours did in 31 seconds. If the mention renders as plain text with no p tag, (c) is missing: check the agent's channel membership and role.

A mention needs both halves. The p tag routes the message and notifies the recipient. The literal @ plus the display name is what draws the chip you can see. One without the other looks correct from exactly one side.
Administration, Users tab, Agents sub-tab. One agent row: its name and user id, the role researcher, Contributor, Enabled, 1 active token, Yes, a date, and Manage keys and Manage tokens buttons. Manage keys is open beneath it: the field for adding a public key, a disclosure for adding a key with a proof of possession, and one bound Buzz key with a shortened npub, 'Added Oct 6, 2026 by' its owner's user id, a BOUND · POSSESSION PROVEN badge and a Retire button.
An agent's key, bound by its owner: Bound · possession proven, added on 6 October by user_003. The Agents tab of ENGRAM's administration page, showing Buzz Bumble, another of our agents; Fizz's row reads the same. The line under the key records who added it, because an agent's key is always somebody's act, never its own. The agent is Enabled with one active token, which is a separate grant from the key. Fizz answering a mention is in Part 4's screenshot, where the whole channel is in frame.

6. Part 3 — Binding the channel: channel.bound

  1. Create the project in ENGRAM. You own it.
  2. Add the agent as a project member.
  3. On the project's page, bind the channel to it as a single binding.

Binding is what makes a doorbell routable: a signal carries a project_id, and the adapter turns that into a room. It also works the other way. The moment you bind, ENGRAM needs the room's own record of itself, and emits channel.bound to have the adapter fetch it.

It happens in seconds. Until both of the room's records are stored, the channel reads awaiting observation. The signal does not wait for a poll: the adapter holds a long poll open, so channel.bound arrives on a connection that is already there. A periodic sweep, a few minutes apart, is the safety net for a missed signal, not the path.

A new binding is fast; a changed one is not. When a binding changes — unbound, rebound, or its binder's key newly proven — the adapter is holding a cached copy and picks up the change within its cache lifetime, a few minutes. ENGRAM's panel updates at once, so the two sides disagree for a short window. A doorbell that seems slow just after a binding change is almost always this.

A bound channel carries state badges. Read them rather than skipping past:

BadgeWhat it tells you
ObservedENGRAM has the relay's own record of this room. Until then the binding routes nothing
Binder in channelwhoever bound the channel is a member of it
Binder in channel · key not proventhe binder is a member, but their chat key is bound and not proven. The panel adds Not routing: the binder's key is not possession-proven — back to Part 1
declared private, observed open, or its reversewhat you declared when binding, against the relay's own record. The relay wins. Harmless, but worth fixing so the panel reads true
A project's Settings, Channels tab. One bound channel marked SINGLE, with green Observed and Binder in channel badges and the line 'Routing: this project's doorbells can go here', above the form for binding another channel.
The project's Channels tab after the relay's record has arrived: one channel bound as SINGLE, marked Observed and Binder in channel. Beneath the badges: “Routing: this project's doorbells can go here”. Note what is not there — no amber badge. Part 1 is why this one is green; the appendix shows the other case.
If the channel is private, add the adapter to it. A non-member cannot tell “private and excluded” apart from “does not exist”, so the adapter reports exactly that — not_visible_to_adapter — rather than guessing. Our channel was private. Add the adapter as a member and it resolves on the next pass.

7. Part 4 — A proposal: proposal.waiting rings you

Have the agent write something and propose it into the project:

create_article(title=…, content_markdown=…, visibility="project")
add_to_project(project=…, artifact_ids=[…])

The order matters. The agent creates the article in its own scope first: passing your project to create_article is refused with a 400, because the project belongs to another user. add_to_project is how a member puts something into a project it does not own.

Because the agent is a member and not the owner, this creates a pending addition — a decision waiting for you. Within seconds, a message from the adapter appears in the bound channel, addressed to you:

@<Your name> A proposed addition to <Project> awaits your decision
https://…/projects?project=…

Two lines, because you are a person. Addressed to an agent, the same signal carries a third: a JSON object naming the tools that close the item.

{"tools":["approve_project_addition","reject_project_addition"],"args":{…}}

Each part of a doorbell has one job:

PartWhat it is for
the @-mentionroutes the message to you and draws the chip
the labelsays what is waiting, never what it contains. Anyone in the room can read a doorbell, so it carries no memory text, no recap digest and no artifact body
the linkwhere to act. Post it exactly as given
the action lineagents only. It names the tools that close the item, so an agent knows what to call without parsing prose. It is a rendering choice, not a permission: the same ids are in the link, and you can act on the item exactly as an agent can
The label narrows itself. A public artifact is named by its title. Anything else reads “A proposed addition to <Project> awaits your decision”, because the title may itself be private, and a notification must not leak what the thing it points at is protecting. An agent on a restricted credential is refused a public artifact with a 403, so with an agent proposing you will normally see the generic form. Have the agent ask for project visibility up front, or it spends a turn discovering the refusal.
A private Buzz channel, Tutorial-11. On the left, messages from ENGRAM @-addressing a person and an agent, each with a one-line label (a proposed addition awaits your decision; your proposed addition was approved; a hand-off from the agent awaits your review), a link into ENGRAM and a JSON line naming tools and ids. On the right, a thread in which the person asks the agent to create and propose an article and later to hand off what it learned, and the agent reports what each call returned, including the artifact id and the recap id.
The whole loop in one room: doorbells from ENGRAM to a person and to an agent, and in the thread beside them the agent reporting each call — the proposal, then the hand-off. Three things to read off it. The chips render because each message carries both halves of a mention. ENGRAM rang the person at 2:46, in the same minute the agent posted its own report — a doorbell does not wait for the actor. And the JSON action line shows on a doorbell to a person: this capture predates 9 October, since when that line is sent to agents only.

8. Part 5 — A decision: proposal.decided rings the agent

Approve the addition, either from the project page or from your own session:

approve_project_addition(project=…, artifact_id=…)

A second doorbell appears in the channel, this time addressed to the agent: “Your proposed addition was approved into <Project>”, with list_project_artifacts as its action. It is in the screenshot above.

What the agent does next is the agent's business, and that is not a disclaimer. If its harness accepts messages from the adapter (Part 2), the doorbell wakes it and it takes a turn. Then it decides. Ours read it, concluded “a notification that my proposal was approved — no action needed”, and said nothing. That is good behaviour, not a fault.

So silence after a doorbell has three readings:

What you seeWhat it means
the agent repliesit woke, and judged a reply useful
silence, and the agent is otherwise aliveit woke and judged otherwise — or its harness never let the message through (Part 2)
silence, and the agent is downthe usual reasons, none of them about doorbells
Nothing in the channel can make an agent act. The action line names the tools that close an item. It is a hint to be honoured, not an instruction to be executed: an agent follows it because its own instructions say to.

Two more behaviours to notice while you are here:

A project page. Its Members section lists the owner and an agent. Its Project Library lists three articles, each tagged ADDED BY AGENT and PROJECT, with Flag and Remove buttons, above the fields for adding another artifact.
What the approvals produced: the project's members — an owner and an agent — and a library of three articles, each marked ADDED BY AGENT. The project records not just what is in it but who put it there, which is the same question Buzz answers for the channel.

9. Part 6 — A hand-off: recap.waiting rings you

This is the part where the two systems stop being adjacent and become one story. The agent finishes a piece of work and hands what it learned to a receiver. The receiver can as well be another agent, which gets the same doorbell with its action line attached; here it is you:

commit_task_memories(context_ref=…, hand_off_to="<your user id>", active_project_id="<the project id>")

active_project_id is what ties the hand-off to the project, and so to its room. A context that belongs to exactly one project does the same, as does active_repo for a project with a repository.

As in Tutorial 10, a hand-off is owned by its receiver: it arrives in your inbox, under your scope, attributed to the agent. What is new is that ENGRAM rings you, once:

@<Your name> A hand-off from <Agent> awaits your review
https://…            ← the Memory Explorer's Suggestions

Then review it on your own terms:

get_recap(recap_id=…)        → what the agent is handing over
review_recap(…)              → keep it, or not
accept_memories(…)           → it becomes yours, and the agent keeps access

get_recap is the recap-by-id tool Tutorial 10 said was coming.

A recap handing over four memories rings once, not four times. Each inbound channel event costs an agent a real turn on a real budget, so one occurrence is one signal — by design, not by luck.

Hand off inside the project, or nothing rings. A signal routes by project_id, and a hand-off ENGRAM cannot attribute to one project carries none. The adapter's rule for that case is do not guess: it posts nothing rather than choose a room, and reports the doorbell back as undeliverable. On our run the signal was emitted, the adapter posted nothing, and the recap was in the receiver's inbox at the same instant. Since v1.18.2 the recap says so itself: Buzz: couldn't deliver — this hand-off names no project. Nothing is lost; the hand-off is still waiting in your Suggestions.
The Memory Explorer, Suggestions tab. One recap titled 'Tutorial 11 run — lessons learned', badged Reflection, 'Handed off by Buzz Fizz (agent)', 2 memories pending. Expanded, it lists the facts, decisions and actions the agent recorded, then two pending memories, each with Accept and Reject, and Accept all and Reject all buttons.
Where the doorbell's link leads: a Reflection recap handed off by the agent, its facts and decisions expanded, and two memories pending with Accept and Reject. The doorbell said something is waiting; this is the thing. Nothing was decided on your behalf — each memory is pending until you accept it. That is the point of a hand-off: an agent proposes what it learned, and a person decides what becomes knowledge.

10. Part 7 — What the room did not reach

Everything above was the integration working. This part is why its shape is safe, and the only way to check it is to look for what is not there.

a. The conversation is not in the knowledge base. Pick a distinctive phrase you typed in the channel and look for it:

recall(query="<that phrase>")

You will get results — ten, on our run — and none of them will be your channel. That distinction is the whole check. Recall answers associatively, so any phrase returns the best-connected things it knows; what matters is that no message from the room is among them, however you phrase it.

ENGRAM does not copy channel conversation. Buzz is the record of what was said and ENGRAM of what is known, and merging them would dissolve the boundary that makes either one auditable.

b. The channel granted the agent nothing in ENGRAM. The agent could propose an artifact because of its own credential and its project membership, not because it is in a room with you. Remove it from the channel: it stops being addressable, and every memory it holds is untouched.

c. The channel decides nothing about what the agent may do. Its tools come from its harness configuration, on its own machine. Nobody in the channel — including you — can widen them by writing a message. That is a third system's job, and it is deliberately not wired to this one.

d. A person with no chat key is not signalled, and that is recorded. Add a second person to the project without a chat key — ours was Jonny Google, as a moderator who can decide — and have the agent propose something. A notification that could not be delivered is a recorded state, not a silence: the item shows Buzz: not signalled — no Chat Key when that person looks at it.

The badge is theirs, which is the right place for it: the cause is a missing key, and only its owner can bind one. Others who can see the item are not told and do not need to be. The item is still decidable by anyone who was reached.

11. What this gives you

12. Appendix — Gotchas to be aware of

Tutorials 9 and 10's appendices still apply; these are the ones specific to doorbells. Troubleshooting covers each in more depth.

  1. No doorbell, and nothing visibly wrong. Check three things in order: the binder's key is proven (Part 1), the channel reads Observed (Part 3), and the signal carried a project_id — a hand-off made outside a project posts nothing, and the recap shows Buzz: couldn't deliver — this hand-off names no project (Part 6).
  2. A binding that looks right and routes nothing. The binder's key is bound but not proven. The screenshot below shows it: three things look correct, and the panel says it is not routing.
  3. A waiting item marked Buzz: not signalled — no Chat Key. That principal has no bound chat key. Part 1.
  4. A waiting item marked Buzz: couldn't deliver — …. The adapter reported it could not post the doorbell, and the badge names why. Nothing is lost. See Troubleshooting.
  5. A mention that renders as plain text, with no chip and no reply. The agent's key is on the relay but not in the channel, or the @ name does not match its profile. Part 2.
  6. An agent that is addressed and never answers. Its harness drops messages from the adapter. Add the adapter's key to the agent's allowlist; a dropped message logs nothing.
  7. not_visible_to_adapter against a channel. The channel is private and the adapter is not a member. Add it.
  8. not_published against a channel. The relay never published the channel's own metadata, so there is nothing for ENGRAM to observe yet.
  9. A binding that stays awaiting observation. The adapter is not running, or cannot reach ENGRAM. Check the Buzz service's /version and the adapter's last used time under Administration → Settings → Chats → System agents.
  10. Binder not in channel. Whoever bound the channel is not a member of it.
  11. A slow doorbell just after a binding changed. The adapter's cached copy — allow a few minutes (Part 3).
  12. A doorbell you have seen before. Delivery is at-least-once: a crash mid-delivery repeats a doorbell, and never silently drops one.
  13. An expired feed cursor. The adapter was down for longer than the feed's retention. It resumes from the oldest available signal and records the gap.
  14. An agent with a grey presence dot. Presence is a short-lived record, kept alive by a heartbeat on a live connection. An agent that polls shows grey while working perfectly. Look for its reply, not its dot.
  15. create_article refused with a 400 naming another user's project. A member cannot file an artifact directly into a project it does not own. Create it in the agent's own scope, then propose it with add_to_project (Part 4).
A project's Settings, Channels tab, on the Trailhead App project. One bound channel, #trailhead-project, marked SINGLE: 'open (as of Sep 4, 2026)', stream, bound by an administrator. A green Observed badge, an amber 'Binder in channel · key not proven' badge and 'declared private, observed open', then the italic line 'Not routing: the binder's key is not possession-proven. Prove it under Chat Keys.' Buttons: Widen to shared and Unbind. Below, the form for binding another channel.
A binding that does not route, on the Trailhead App project: Observed and binder in channel, but “Binder in channel · key not proven”. Beneath it: “Not routing: the binder's key is not possession-proven”. The channel is observed, the binder is in it and the key is bound, so the panel looks almost right — which is why this is the more useful picture of the two. Its third badge, declared private, observed open, is the harmless mismatch described in Part 3.
Companion reference: Buzz & Chat Keys — chat keys, proofs, channel bindings and doorbells, in full — and Using Buzz with ENGRAM.