Circles

Circles are consumer-owned groups that work across apps. A consumer creates a Circle (like “My Family” or “Marketing Team”), invites members by email, and connects it to any circle-enabled app. Every member’s AI conversations in connected apps share the circle’s memory, files, and events — so the AI knows about the whole group, not just one person.

How It Works

Circles are email-anchored. Since consumers are per-app but circles are cross-app, all identity is based on email address — not app-specific user IDs. This means a consumer’s “Family Circle” works in any circle-enabled app where they provide the same verified email.

1. A consumer creates a Circle and becomes the owner
2. The owner invites members by email — invitees receive an email notification
3. Members accept the invite and the circle is active
4. Any member can connect the circle to an app they use
5. Connected apps inject the circle’s context (memory, members, events) into the AI’s system prompt
6. The AI knows about the group and can reference shared information

Key Concepts

Email-Anchored Identity

Circles don’t use app-specific consumer IDs. A consumer who logs into App A and App B with the same email sees the same circles in both apps. This is what makes circles “cross-app” — the identity follows the email, not the app.

Circle Memory

Each circle has a shared memory field — a free-form text store that any member can read or write. The AI can reference this memory during conversations, and apps can append to it programmatically.

Think of it as a shared notebook for the group. One member might add “Dad’s birthday is March 15” in a family planning app, and a different member asking a gift recommendation app will have that context available.

Circle Events

Circles have a sequential event log. Events are written by apps or members and can be polled by connected apps using a cursor-based pagination model. Event types include membership changes (file_shared, file_unshared) and custom app-defined events.

Connected apps track an eventCursor so they only process new events since the last check.

App Connections

A circle isn’t automatically available in every app. Members explicitly connect circles to specific apps. When an app is connected, it can read the circle’s memory, members, and events to provide group-aware AI responses.

For Builders: Enabling Circles

To enable circles for your app, add circle.enabled: true to your app’s capabilities. This is currently configured through the app settings.

Once enabled, consumers with verified emails will be able to create circles, invite members, and connect circles to your app. The circle context is automatically injected into the AI’s system prompt for connected circles.

What the AI Sees

When a consumer with connected circles starts a chat, the AI receives circle context including:

• Circle name and description
• Shared memory content
• List of members with names, emails, and roles
• Any role descriptions members have set

This allows the AI to provide personalized, group-aware responses.

For Consumers: Using Circles

Creating a Circle

Invitations

• Only the circle owner can invite or remove members
• Invited members see the circle in their pending invites list
• Members can accept or decline an invitation
• Declined invites can be re-sent by the owner

Roles

Role	Permissions
Owner	Full control: invite/remove members, edit circle, delete circle, read/write memory
Member	Read/write memory, connect/disconnect apps, view members, share/unshare files

Each member can have an optional role description (like “Budget manager” or “Trip planner”) that is included in the AI’s context, helping the AI understand each person’s role in the group.

Connecting to Apps

Once you are an active member of a circle, you can connect it to any circle-enabled app you use. The connection is per-app — connect to the apps where you want group context available.

Circles also support auto-connect: when you log into a circle-enabled app, your active circles are automatically connected.

File Sharing

Members can share files from their Consumer Brain storage with the circle. Shared files are accessible to all circle members across connected apps.

• Share a file: The file must be owned by you (in your Consumer Brain)
• Unshare: The original sharer or the circle owner can remove a shared file
• Download: Any active member can view and download shared files via signed URLs

File sharing events (file_shared, file_unshared) are recorded in the circle’s event log.

API Reference

All circle endpoints are consumer-authenticated and require a verified email. Routes are mounted under /:appNameId/circles/.

Circle CRUD

Method	Endpoint	Description
GET	/circles	List your circles + pending invites
POST	/circles	Create a new circle
GET	/circles/:id	Circle detail + member list
PATCH	/circles/:id	Update name/description (owner only)
DELETE	/circles/:id	Delete circle (owner only)

Membership

Method	Endpoint	Description
POST	/circles/:id/invite	Invite a member by email (owner only)
POST	/circles/:id/accept	Accept a pending invite
POST	/circles/:id/decline	Decline a pending invite
DELETE	/circles/:id/members/:email	Remove a member (owner only)

Memory

Method	Endpoint	Description
GET	/circles/:id/memory	Read the circle’s shared memory
PUT	/circles/:id/memory	Write or append to memory

The write endpoint supports two modes via the mode field: replace (overwrite) or append (add to existing).

Events

Method	Endpoint	Description
GET	/circles/:id/events	Read events (cursor-based)

Query parameters: after_seq (cursor), limit (max 100), event_type (filter).

App Connections

Method	Endpoint	Description
POST	/circles/:id/connect	Connect circle to the current app
DELETE	/circles/:id/connect	Disconnect circle from the current app

File Sharing

Method	Endpoint	Description
GET	/circles/:id/files	List shared files
POST	/circles/:id/files/:fileId	Share a file to the circle
DELETE	/circles/:id/files/:fileId	Unshare a file
GET	/circles/:id/files/:fileId/url	Get a signed download URL

Use Cases

Use Case	Example
Family planning	Share preferences, schedules, and dietary needs across meal planning, travel booking, and gift recommendation apps
Team collaboration	A marketing team shares campaign briefs and brand guidelines that every AI tool they use can reference
Study groups	Students share notes and files, and any tutoring AI they connect to knows the group’s curriculum
Client management	A consulting team shares client context so every AI tool produces consistent, client-aware outputs
Household management	Roommates share household info (utilities, maintenance contacts, schedules) across different AI assistants

Troubleshooting

“Circles are not enabled for this app” (403)?

• The builder has not enabled circles in the app capabilities
• Contact the app creator to request the feature

“Verified email required” (401)?

• You must verify your email through the OTP flow before using circles
• Check your email for the verification code after signing up

Cannot invite members?

• Only the circle owner can invite or remove members
• Verify the email address is correctly formatted

Circle not showing in another app?

• You must connect the circle to each app separately
• Verify the other app has circles enabled
• Make sure you are using the same verified email in both apps