# Circles

Consumer-owned groups that share memory, files, and events across multiple AI apps.

---

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.

> **Warning:** Circles require the builder to enable the feature in the app's capabilities. Consumers must have a verified email (OTP-confirmed) to create or join circles.

## 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


  **1.** 
    <strong>Verify Your Email</strong>

    Circles require a verified email. If you haven't already, verify your email through the OTP flow.
  


  **2.** 
    <strong>Create the Circle</strong>

    Navigate to the circles section and create a new circle with a name and optional description.
  


  **3.** 
    <strong>Invite Members</strong>

    Add members by email. They will receive an invite notification and can accept or decline.
  


### 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](/docs/guides/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

> **Note:** Circles pair well with [Consumer Brain](/docs/guides/consumer-brain) for persistent file sharing, and [User Memory](/docs/guides/user-memory) for individual context that complements group memory.