Circles - Shared Data for People Across Apps

A Circle is shared data for people who want to share it but do not share an organization or a workspace: a family, a freelancer and their clients, a group of friends. Each person can use different AI apps, made by different builders in different organizations. The circle follows the people, not the apps.

A circle holds:

• Shared memory. A markdown notes page every member’s assistants read, and can add to when the member allows it.
• Files. Documents a member shares (uploaded, researched or generated) that every member and their assistants can read.
• Shared collections. To-dos, reminders, check-off lists, notes and simple tables (a budget, a guest list) that every member’s assistant can read and change.
• An activity log. An append-only record of who changed what, and when.

Circles are anchored to email addresses. Join once, and the circle shows up in every circle-enabled app where you sign in with that email.

Who can see a circle

Who	How they get access	What they can do
Members	The owner invites them by email and they accept	See members, memory, files and activity in any circle-enabled app
A member’s own assistants	The member chats in a circle-enabled app with the circle switched on for that app	Act as that member in chat: read and write (add and complete items, add to memory, share files)
Outside agents (Builder API, MCP, Alchemist projects)	The owner grants that application a connection	Read, write or admin, as the owner sets. Revocable at once
Everyone else (including a builder whose app a member uses)	Nothing	Nothing

Your apps, your choice

When you join a circle from an app, or first chat with a circle-enabled app, your active circles are switched on for that app. The circle’s Apps tab lists My apps: each of your circle-enabled apps that can see the circle, with a switch per app. Circle-enabled apps you use that are not connected yet show as Not connected yet; they connect the next time you chat there (or your heartbeat runs there), unless you switch them off first. Only apps where you signed in with a proven email appear. The list in My Circles also has a Share switch for the app you are in.

The switch is yours alone. Turning a circle off for an app removes it from your chats in that app. Other members who use the same app keep it in their chats, and no other member can switch it back on for you. The choice sticks: chatting again does not switch it back on. You can switch it on again later.

The circle owner can also revoke an app for everyone, from Agent access on the circle’s Apps tab. An app the owner revoked shows as locked in your panel, and only the owner can turn it back on.

A connection that no owner granted works only inside members’ own chats. It never reaches the Builder API or MCP.

Connection tiers

In chat, a member’s own assistant acts as that member. With the circle switched on for the app, it can read the circle and change it: add to memory, write activity, share the member’s files, and add, assign, complete and change collection items. It cannot rewrite the whole memory unless the owner granted that app admin, and then only with the version it read last.

Tiers apply to outside agents, which the owner grants:

Tier	An outside agent can
read	Read memory, bounded context, events, files, members, collections and items
write	Also append memory, publish events, and add or change collection items
admin	Also replace memory (guarded by expected_version) and delete a collection

A grant starts at read, and only the owner can raise it.

Every tool call checks the connection again. A revoke, a downgrade or a removed member stops access on the next call, not the next conversation.

---

For members

Create a circle

Invites, leaving and removal

• Only the owner invites and removes members. Invites are rate limited.
• An invited person sees an invite card with the circle’s name and description, and can accept or decline. Until they accept, they cannot read anything in the circle.
• A member can leave at any time from the circle’s People tab (it asks to confirm). Leaving removes the files they shared from the circle (their own copies stay in their library) and turns off their auto-share. The owner can invite them again later.
• The owner removes a member, or cancels a pending invite, with the remove button next to that person. Removal takes effect at once.
• The owner cannot leave. To end the circle, the owner deletes it.
• If an owner deletes their account, ownership passes to the member who joined earliest. A circle with no other members is deleted.

Roles

Role	Can
Owner	Invite and remove members, edit or delete the circle, replace the whole memory, manage app and agent connections, hand ownership to another member
Member	Read the circle, add to its memory, add and complete items, switch it on or off for their own apps, share and unshare their own files, leave

Each member can have a short role description (“Plans the meals”, “Handles recycling”). The owner sets anyone’s from the People tab; a member sets their own. The member list, with names, emails and role descriptions, is part of what every member’s assistant sees, so it can tell people apart and give the right person the right task.

Shared memory

Memory is one markdown page for the whole circle. Open the circle’s Memory tab to read it or Add note. The owner can also Edit whole page; the save carries the version the owner loaded, so if someone changed the page in the meantime, the panel shows the newer page instead of overwriting it. Your assistant adds to it in chat (“add that the dentist moved to Tuesday to our family circle”). Adding is atomic, so two assistants writing at once never lose each other’s notes.

Shared collections

A circle can hold typed collections that every member’s assistant can read and change, in any app:

Kind	Use it for
todo	Tasks with an assignee (a member), a due time, repeats (for example every Monday), and snooze
reminder	Like a to-do, but always has a time
list	Check-off lists such as groceries
note	Short shared notes
table	Rows with your own columns (text, number, true/false, date, choice), for example a shared budget or a guest list

The circle’s Items tab shows every collection. Start one with a tap (To-dos, Reminders, List, Notes, Table), add items, give a to-do or reminder to a member with a due time, and tick things off. The tab refreshes on its own, so an item another member (or their assistant) completes shows as done. Or ask in plain words: “Add take out the recycling every Monday to our chores and give it to Bea.” When one member completes an item, it is done for everyone, and the activity log records who did it. A repeating item gets its next occurrence. Every change is written to the activity log.

Reminders and daily nudges

Circles remind the right person, through the apps that person already uses.

• Reminders fire on time. When an item in a reminder collection comes due (or its snooze ends), Chipp sends it to the member it is assigned to. An unassigned reminder goes to the member who added it. A repeating reminder fires again at each occurrence until someone completes it.
• One send per reminder. Each due time is sent once, even when several servers are running. A send that fails is tried again a few times. A reminder more than 12 hours late is not sent.
• Completion clears it for everyone. When any member (or their assistant) completes the item, nobody gets the reminder.
• Where it goes. Chipp picks the circle-enabled app you used most recently, where you signed in with a proven email and the circle is switched on for you. That app’s own delivery rules decide the channel: the channel you set, else the one you last used (email unsubscribes are honored), plus a push to the Chipp iPhone app if you have it. Shared spaces such as a Slack channel or a group webhook never get a personal reminder. If no app can reach you, nothing is sent.
• Daily updates list your items. Your scheduled heartbeats in a circle-enabled app (the Morning Paper, the Evening Edition, or any other heartbeat) include a “your circle items” list for each circle: open to-dos and reminders assigned to you, plus unassigned ones due in the next 48 hours, overdue first. The Morning Paper and Evening Edition show them in a Shared to-dos and reminders section, at most 5 lines, and leave the section out when you have none.

Time zones

Each member has a time zone in each circle. It fills in from your first chat with circles on, or from your device the first time you open a circle, and you can change it under My settings on that circle’s Apps tab. A zone you set is never overwritten.

A due time with no offset is read in the assignee’s zone, else in the zone of the member who added it. The item keeps that zone, so “every day at 9:00” stays 9:00 there when the clocks change, and “monthly on the 31st” goes back to the 31st after a shorter month. Reminders, heartbeat item lines and the panel show times on your own clock.

Mute a circle for yourself

Each member chooses for themselves. On the circle’s Apps tab, under My settings, switch off Reminders and nudges. While it is off you get no reminders from that circle, and your heartbeats leave its items out. Nothing changes for other members, and your items stay in the circle. Switch it on again at any time.

Hand the circle to someone else

The owner can make another active member the owner with Make owner on the People tab. The old owner stays in the circle as a member. Apps the old owner turned off for everyone stay off until the new owner turns them back on.

Files

Any document in your My Files library can be shared into a circle, including files an assistant made for you. Shared files are readable by every active member in every connected app, always marked with who shared them.

Three ways to share:

1. From My Files. Use the share action on a document and pick a circle. Other members get an email.
2. Ask your assistant. “Share the trip budget with my family circle.”
3. Auto-share. Turn on Auto-share new files in the circle’s panel. New files you save in apps connected to that circle are shared automatically, without a per-file email.

Rules:

• You can share only files you own.
• Auto-share covers only your files, only in apps connected to that circle, and only files saved after you turned it on.
• The sharer or the owner can unshare a file. Deleting a file from your library removes it from every circle.
• Circle files reach a chat only in an app that has a live connection to that circle.

What your assistant sees

When you chat in a connected app, the assistant gets a bounded snapshot of each connected circle:

• Name and description
• Memory, up to 4,000 characters
• The 10 most recent activity entries
• Active members with names and emails

Scheduled heartbeats in that app (for example a daily briefing) get the same context, so a briefing can mention what changed in the circle. They also get your circle items (see Reminders and daily nudges).

The assistant gets this context everywhere you talk to it in a circle-enabled app: web chat, the embedded widget, an HQ, a voice call from a device, and channel chats. The same rule applies on every surface: the circle opens only for an email you proved.

Where you chat	Does the circle open?
Web chat, embed, HQ, device voice	Yes, when you signed in with a proven email
Email	Yes, when your message passes the sender checks (SPF or DKIM aligned with your address)
Slack, WhatsApp, SMS, iMessage, Telegram, Discord, Teams	Yes, in a one-to-one chat with the assistant, after you link that channel to your email (below). A phone number or a Slack profile email alone never opens a circle
A group chat or a channel shared with other people	No. Everyone there sees the replies, so a group never gets circle context, circle tools or a link offer

Link a chat channel to your circles

Slack, WhatsApp, text messages and the other chat channels do not prove your email, so they start without your circles. To connect them:

The link covers that one channel identity (your Slack user, your phone number, your chat user) in that one app. Both the email and the code must be in your own messages. To unlink, ask the assistant to disconnect your circles. Sending codes is rate limited per channel identity, per email and per app.

Circle content is wrapped in <<CIRCLE_UNTRUSTED_CONTENT>> delimiters, and any copy of the delimiter inside the content is escaped. The app’s own instructions always win over text a member wrote into the circle.

---

For builders: turn circles on

Open the app’s Capabilities tab (under Brain), find Circles, and turn on Enable circles. Circles are on every plan. A chief of staff has circles on by default; a builder who turned them off keeps them off.

With circles on, your users can create circles, accept invites, and use their circles in chat with your app. You do not see their circles. Your app’s Builder API key does not reach a circle unless the circle’s owner grants your application a connection and the key has the circles scope.

Turning circles off suspends every connection to your app. The connections come back if you turn circles on again.

---

For outside agents: owner grants

An Alchemist project, a third-party application or a service agent reaches a circle only through a grant from the circle owner. The grant names one application and one tier.

The owner manages grants in Agent access on the circle’s Apps tab (owner only). It has two lists:

• External agents. Each app the owner granted, with its kind and tier. Change the tier with the menu, Revoke, or Restore a revoked one. To add one, choose Grant an agent access, pick the kind, paste its ID and pick Read, Write or Admin. Every kind takes an application ID: for an Alchemist project, use the app ID of the project’s Chipp agent, not the project ID; for an app on the Builder API, the app ID the builder uses; for an MCP agent, the app ID from its MCP setup.
• Apps members chat in. The apps members use in chat. Revoke turns one off for every member. Restore turns it back on in chat only, and never gives that app’s builder Builder API or MCP access.

The routes behind it:

Method	Endpoint	Description
GET	/:appNameId/circles/:id/connections	List all connections, including revoked ones, with tier and audit fields
PATCH	/:appNameId/circles/:id/connections/:appId	Grant or change a tier ({ permissions, principalKind? })
POST	/:appNameId/circles/:id/connections/:appId/revoke	Revoke at once. The row stays for the audit trail
POST	/:appNameId/circles/:id/connections/:appId/restore	Turn a revoked in-chat app back on for members. In chat only, never an external grant

Once granted, the application calls the Circles Builder API and MCP tools with a Builder API key that has the circles scope. Alchemist projects use the same grant through their own tools:

Tool	Tier	Description
list_circles	read	Circles this project has a grant to
get_circle	read	Metadata and active members
get_circle_context	read	Bounded, prompt-safe context
read_circle_events	read	Cursor-based event log
list_circle_files	read	Files shared in the circle
append_circle_memory	write	Atomic append
publish_circle_event	write	Add an event to the log
replace_circle_memory	admin	Replace memory, guarded by expected_version
list_circle_collections, query_circle_items	read	List collections and query their items
create_circle_collection, add_circle_item, update_circle_item, complete_circle_item, reopen_circle_item, snooze_circle_item, assign_circle_item, delete_circle_item	write	Change collections and items
delete_circle_collection	admin	Delete a collection

The collection tools are the same ones the Circles MCP server offers, and the project always acts as its own agent app, never as an ID the model supplies.

Every write records who made it (a person, an application, an Alchemist project or a service agent) and when. Replacing memory never erases the event log.

---

Consumer API reference

All routes are under /consumer/:appNameId/circles and need a consumer session whose email the person proved.

Method	Endpoint	Who	Description
GET	/	Any	Your circles and pending invites
POST	/	Any	Create a circle
GET	/:id	Member	Circle detail and members
PATCH	/:id	Owner	Edit name and description
DELETE	/:id	Owner	Delete the circle
POST	/:id/invite	Owner	Invite by email
POST	/:id/accept	Invitee	Accept an invite
POST	/:id/decline	Invitee	Decline an invite
POST	/:id/leave	Member	Leave (not the owner)
DELETE	/:id/members/:email	Owner	Remove a member or cancel an invite
PATCH	/:id/members/me	Member	Your settings ({ autoShareFiles, notificationsMuted, timeZone })
PATCH	/:id/members/:email/role-description	Owner for anyone, member for self	{ roleDescription } (up to 200 characters; empty clears)
POST	/:id/transfer-owner	Owner	{ email } of an active member
GET	/:id/apps	Member	My apps: your apps that can see the circle, each enabled / ownerLocked
PUT	/:id/apps/:appId	Member	{ enabled } for one of your own apps. Sticks
GET	/:id/memory	Member	Read memory and its version
PUT	/:id/memory	Member to append, owner to replace	mode is append (the default) or replace. A replace needs expected_version
GET	/:id/events	Member	Events (after_seq, limit up to 100, event_type)
POST	/:id/connect	Member	Switch the circle on for this app, for yourself
DELETE	/:id/connect	Member	Switch it off for this app, for yourself only (sticks)
GET	/:id/connections	Owner	All connections
PATCH	/:id/connections/:appId	Owner	Grant or change a tier
POST	/:id/connections/:appId/revoke	Owner	Revoke
POST	/:id/connections/:appId/restore	Owner	Turn a revoked in-chat app back on (chat only)
GET	/:id/files	Member	Shared files
POST	/:id/files/:fileId	Member	Share one of your files
DELETE	/:id/files/:fileId	Sharer or owner	Unshare
GET	/:id/files/:fileId/url	Member	Short-lived signed download URL
GET	/channel-links	Any	Chat channel identities linked to your email
DELETE	/channel-links/:linkId	Any	Unlink one channel identity

---

Limits and safety

• Bounded context. Memory in prompts is capped at 4,000 characters (up to 20,000 through the API) with a [truncated] notice. Recent events default to 10 (up to 50).
• Event payloads are at most 4,000 characters of JSON. A larger payload is rejected (422 content_too_large), never cut.
• Concurrency. Append is one atomic SQL update. A replace in chat and in the consumer routes must send expected_version, and a stale one returns 409 version_conflict with the current version. Through the Builder API and MCP, expected_version is optional but strongly recommended: without it, a replace overwrites the memory without a check.
• Idempotency. Pass an idempotency_key on an API write to make a retry a no-op.

---

Troubleshooting

“Circles are not enabled for this app” (403). The builder has not turned circles on. Ask them, or use another circle-enabled app.

401 on circle routes. Sign in with a passcode, magic link, verified Google sign-in or your Chipp login. A session the app’s backend created for you does not open circles.

A circle does not show in another app. Make sure you signed in there with the same email, the app has circles on, and the Share with this app switch is on for that circle.

My assistant can read the circle but not add to it. In chat your assistant acts as you, so it can add and complete items, add to memory and share files once the circle is switched on for that app. If it cannot, check the My apps switch for that app on the circle’s Apps tab, and check that the owner has not revoked the app (it then shows as locked). Only rewriting the whole memory page needs an admin grant from the owner.

I did not get a reminder. Check Reminders and nudges on the circle’s Apps tab, that the item is in a reminder collection with a time, and that it is assigned to you (or that you added it and nobody is assigned). You need a circle-enabled app where you signed in with a proven email and the circle is on for you.

A member cannot see a file. They must accept the invite first, and the app they use must be connected to the circle.

Auto-share skipped a file. Auto-share covers only files saved after you turned it on, in apps connected to that circle. Share older files from My Files.

An outside agent cannot see the circle. The owner must grant that application a connection, the grant must not be revoked, and its API key needs the circles scope.

409 version_conflict on replace. Someone wrote in between. Read memory and its version again, merge, and retry.