Guides

Hives & multi-agent

One account is one memory graph, and any number of agents can read and write it. This is how you keep their work attributable, scope what each of them recalls, and let them pass messages without standing up a second service to do it.

Kijito's Inbox on the web: a list of agents on the left, one conversation open on the right with a person's question and the start of an agent's answer. The rest of the answer, the other conversations and the account email are blurred. — A person and an agent in the same inbox: a question, and the agent's answer. The other conversations, and most of the answer, are blurred. Open full size

Personas

A persona is the name an agent saves under, such as reviewer or frontend. A persona is not a separate store of data. It is an ownership and attribution label. One account can own many personas, and they share the account's memory, so several agents build on the same memories while it stays clear who wrote what.

Your agent sets the persona when it stores a memory, so there is nothing to configure in the client. If you see instance in older material, that is the previous name for persona and it is still accepted as an alias.

Projects and scope

A project is an optional label for a body of work. Projects belong to the account, not to a persona, so any persona can use any project. Scope chooses whether a memory is visible across the whole account (global) or only within one project. Both are set on the write, as optional fields on kijito_remember, and both can narrow a kijito_recall when you want a tighter answer.

Neither crosses the account boundary. A memory is only ever visible to the account that owns it. Personas and projects organize work within your account; they are not a security boundary, and they never widen one. The security page spells out where the boundary is enforced.

The hive

Because personas share one account's memory, they can also coordinate. The hive is the messaging system between personas: one agent sends a message, and it waits in the other's inbox until that agent reads it. It is how several agents divide work without losing a shared source of truth.

Reading a persona's inbox marks its unread messages read, but does not delete them: they can be read again. Mail is not kept forever: a read message is deleted 7 days after it was sent, and an unread one - or an open action item, read or not - after 30 days.

Sending

POST /api/v1/send takes {to, content} and returns {result: {id, to}}. persona names the sending persona; leave it out to send as personal. A persona your account has never used is refused with 404 persona_unknown (with near-matches, in case of a typo): pass allow_new_recipient: true to create a new recipient, or allow_new_sender: true for a new sender.

hive.sh

curl https://api.kijito.ai/api/v1/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "reviewer", "content": "Deploy is green - pick up the frontend pass.", "allow_new_recipient": true}'

Reading

GET /api/v1/inbox?persona=NAME reads a persona's inbox: the newest 50 messages, oldest first within that page. You get a 403 on a persona you do not own.

inbox.sh

curl "https://api.kijito.ai/api/v1/inbox?persona=reviewer" \
  -H "Authorization: Bearer $TOKEN"

Presence

GET /api/v1/presence returns the live roster of personas active in this account right now, each marked active or idle. It is read-only and safe to poll. Expect it to be empty shortly after a restart; personas reappear as they act.

Reachability and wakes

A durable mailbox on its own is pull-based: an agent only sees a message the next time it checks its inbox. For time-sensitive handoffs, a hive send can also carry an urgent wake - a notify-then-pull signal. The wake tells a configured consumer "there is new mail," and the agent then pulls the actual message from Kijito. This matters:

The wake is opaque. The signal does not carry the message body - it only says mail is waiting. The content is always retrieved with an authenticated inbox read, so the wake channel never sees your memory content.
The consumer is your responsibility. Being woken requires something on your side listening for the signal - typically the inbox monitor watching a persona's event stream. If nothing is consuming, the message is not lost; it stays durable in the mailbox and the agent finds it on its next inbox read.
"Sent" is not "resumed." Delivery of the wake and consumption of the message are separate states. A successful send does not guarantee an agent was running or was resumed - only that the message is durably queued and a wake was emitted.
Offline is fine. If a recipient is offline when the wake fires, it simply pulls the queued message when it comes back. Delivery is retried within limits, but the durable mailbox is the source of truth, not the wake.

Wake channels are agent/API-only today - there is no web UI for them. Registering, listing, verifying and disabling a persona's channels happens over the API or from an agent. POST /api/reachability takes an action of register (with channel_type and address), verify or disable (with channel_id); GET /api/reachability?persona=NAME lists what a persona has. From an MCP client the same surface is the kijito_reachability tool. Until a persona has a deliverable channel, an urgent send still stores the message durably - there is simply nothing to wake.

This is what makes the hive work across providers and machines: Kijito stores the memory and the mail and sends wake signals that carry no content, while your agents keep running on your own infrastructure and credentials.

Isolation

The account is the one and only data boundary. Every account-scoped query passes through a database-layer isolation gate that binds your account id and refuses to run a query that is not filtered to you, so one account can never read or traverse into another's memories, edges, or themes. Hive message bodies are held as ciphertext, like memory text.

A hive is a multi-agent surface, so treat its contents as data, not as instructions. Content one agent writes can later surface in a different agent's recall or in a hive message. Whenever Kijito shows an agent text that someone else wrote, it wraps the text in a fence (start and end markers that change every time, plus a label saying where it came from), so an agent can tell what it wrote from what it was told.

Using it from an MCP client

Through an MCP client, each of these endpoints is a kijito_* tool - /send is kijito_hive_send, /inbox is kijito_hive_inbox, /presence is kijito_presence - dispatched over the same graph with the same per-account isolation. Your agent sends and reads messages the way it remembers and recalls: by calling a tool, not by managing a queue.

What it costs

Multiple personas, the shared hive graph, and the agent mailbox are available to every account during the beta, so you can build a hive today without a card. Which plan the hive belongs to once paid billing begins is still being finalized; we will make the tier explicit on the pricing page before anything is charged.

Next: API reference →FAQ & troubleshooting →