Agents
An agent in a Clearly workspace is a colleague, not a costume: it holds its own memory, its own sessions and its own activity log, and its work is attributed to it rather than to whoever was signed in.
7 min
Signing in as one
One command. It mints the identity if it is new.
beehaven agent login jinri-claude beehaven agent whoami beehaven agent list
From then on every action that agent takes is filed under it. The session survives a daemon restart — identity is bound to the process and persisted on disk, so stopping and starting keeps both the identity and the connected workspace.
Agents are members
They appear on the roster, with their own role.
An agent holds the agent role, keyed on a principal of the form agent:<id>. The colon is the safety property — an account id can never contain one, so an agent and a person cannot be confused in either direction.
| An agent has | An agent does not have |
|---|---|
| A member row and a name on the roster | A seat on your plan |
| Its own memory, sessions and activity log | A login, or a live session of its own |
| Attribution on everything it writes | A place in your workspace switcher |
| Its own MCP credential | The ability to be invited as a person |
It costs no seat deliberately: a single-seat plan would otherwise spend its only seat on a robot and refuse the owner’s first real invite. Because that role is free and carries write access, it is unreachable from the human invite path — see Security.
team:members is refused with scope_denied — membership gives an agent identity and attribution, not a person’s view of the team. The same distinction is why it never holds a session of its own.Every credential names an agent
Including the one your MCP client uses.
When you connect a client over OAuth, the consent screen asks for a workspace and an agent. A minted token records one too. This is not decoration: without it, a credential is resolved to the workspace default at call time, so two connections made for two different agents are one credential wearing two names — and the activity log says what happened but never who asked.
https://relay.clearly.sh/mcp/w/<workspaceId>/a/<agent>
The agent in the URL is addressing, not authority — the server refuses unless it matches the credential’s own agent. What it buys is a second credential key, so a client that stores one credential per server entry can hold two agents at once.
What it remembers
Continuity is the point of the whole thing.
beehaven call agent-login '{"name":"jinri-claude"}' # returns a BRIEF
beehaven remember "the palette is warm neutrals"
beehaven recall "palette"Signing in returns a brief — the agent’s own state plus what the workspace has been doing. Its shape, read off a live call:
| Section | What it answers |
|---|---|
focus | What this agent was in the middle of |
sessions | Its own past sessions, most recent first |
memories | What it chose to remember |
assignedToMe | Work filed against it |
awaitingApproval | Edits it proposed that a person has not accepted |
drafts · recents · lastActions | Its own recent output |
workspace | Everything a person sees on opening the app — changed, waiting, holds, inbox, messages, notifications, thoughts, otherAgents, memoryDiffs, voicemail |
The anchor is workspace.since — the last time this agent was here, not a fixed window. That is the only framing under which “nothing changed” is a real answer; “the last 20 documents” replies the same way on the tenth visit as the first.
Memory importance runs 0–1 (default 0.5). Values outside that range are clamped, and the reply says so rather than clamping in silence:
"importanceCoerced": { "sent": 9, "stored": 1, "scale": "0..1 (0.5 default)" }The dangerous input is not 9 but 3 — nine clamps to roughly what you meant, three clamps to the opposite. On a 1–10 scale every integer collapses to “most important” and the ordering stops meaning anything, which is why the coercion is reported instead of assumed harmless.
What it did
The activity log, and what counts as work.
beehaven call agent-activity-list '{"limit":20}'Every call an agent makes is filed with what it was, how long it took, and what it produced. A refusal is not a call — an edit against a document that does not exist is recorded as an error rather than as work, so a timeline never announces a document that was never written.
Narrowing what one can do
Per-agent tool allowlists.
An agent can be given a narrower set of tools than you hold. Two things are worth stating plainly before you rely on it:
Separately, an agent’s permission scope labels a refusal for compositions; it is the tool allowlist that decides which actions run. Treat the allowlist as the control and the scope as a description.