Docs/Guides/Design & Experience

    Circles

    Last updated · MAR 2026·Read as Markdown

    User-owned groups that share memory, files, and events across multiple AVCodex agents.

    Circles are user-owned groups that work across agents. A user creates a Circle (for example "BOS-HQ AV Ops Team", "ACME Account Programmers", or "Vendor Bid Group: 40-room Refresh"), invites members by email, and connects it to any Circle-enabled agent. Every member's chats in connected agents share that Circle's memory, files, and events. The agent knows about the whole group, not just the person typing.

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

    Circles are email-anchored. Users are scoped per agent, but Circles are cross-agent, so identity is based on email, not per-agent IDs. A user's "BOS-HQ AV Ops Team" Circle works in any Circle-enabled agent where they sign in with the same verified email.

    1. A user creates a Circle and becomes the owner.
    2. The owner invites members by email. Invitees receive an email notification.
    3. Members accept and the Circle is active.
    4. Any member can connect the Circle to an agent they use.
    5. Connected agents inject the Circle context (memory, members, events) into the system prompt.
    6. The agent now knows about the group and can reference shared information.

    Email-Anchored Identity#

    Circles do not use per-agent user IDs. A programmer who signs into Agent A and Agent B with the same email sees the same Circles in both. The identity follows the email, which is what makes Circles cross-agent.

    Circle Memory#

    Each Circle has a shared memory field: a free-form text store that any member can read or write. The agent can reference this memory during conversations, and agents can append to it programmatically.

    Treat it as a shared notebook for the group. A senior programmer might write "Standard QSC Lua audio routing module is in repo /qsys-modules/audio-routing-v3. Use it for every BOS-HQ project." Another programmer asking a different agent for help on the same job has that context immediately.

    Circle Events#

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

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

    Agent Connections#

    A Circle is not automatically available in every agent. Members explicitly connect Circles to specific agents. When connected, the agent can read the Circle's memory, members, and events to give group-aware answers.

    Set circle.enabled: true in your agent's capabilities. Currently configured through agent settings.

    Once enabled, users with verified emails can create Circles, invite members, and connect Circles to your agent. The Circle context is automatically injected into the agent's system prompt for connected Circles.

    What the Agent Sees#

    When a user with connected Circles starts a chat, the agent receives Circle context including:

    • Circle name and description.
    • Shared memory content.
    • Member list with names, emails, and roles.
    • Any role descriptions members have set.

    This is what makes group-aware answers possible: a project-management agent can say "Jordan owns commissioning, send the punch list to her" because the Circle context says so.

    Creating a Circle#

    1. Verify Your Email

    Circles require a verified email. If you have not done it, verify through the OTP flow.

    2. Create the Circle

    Open the Circles section and create a new Circle with a name and an optional description.

    3. Invite Members

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

    Invitations#

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

    Roles#

    Role Permissions
    Owner Full control: invite or remove members, edit Circle, delete Circle, read and write memory.
    Member Read and write memory, connect or disconnect agents, view members, share or unshare files.

    Each member can have an optional role description (like "Lead Crestron programmer" or "Site PM") that is included in the agent's context. The agent uses it to understand each person's role in the group.

    Connecting to Agents#

    Once you are an active member, you can connect the Circle to any Circle-enabled agent you use. The connection is per agent. Connect to the agents where you want group context available.

    Circles also support auto-connect: when you sign in to a Circle-enabled agent, your active Circles connect automatically.

    File Sharing#

    Members can share files from their Consumer Brain storage with the Circle (a Q-SYS design file, a Crestron SIMPL Windows project, an AS-built PDF, a manufacturer spec sheet). Shared files are accessible to every member across connected agents.

    • Share a file: the file must be 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 via signed URLs.

    File-sharing events (file_shared, file_unshared) are recorded in the Circle's event log.

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

    Circle CRUD#

    Method Endpoint Description
    GET /circles List your Circles and pending invites
    POST /circles Create a new Circle
    GET /circles/:id Circle detail and member list
    PATCH /circles/:id Update name or 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).

    Agent Connections#

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

    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 Case Example
    Project team Circle A 40-room corporate refresh team (PM, lead programmer, commissioning tech) shares the BOM, AS-built drawings, and punch list across the project-management agent and the field-tech agent.
    Account team Circle A managed-services AV firm's team for one named client shares client preferences, room layouts, and standing standards.
    Programmer guild Circle The Crestron programming team shares reusable SIMPL# modules, gotchas, and naming conventions every internal agent can read.
    Bid team Circle An RFP response team shares the working draft, vendor quotes, and design notes across the spec-sheet agent and the proposal-writing agent.
    Site Circle A higher-ed AV ops team shares standard operating procedures, classroom notes, and term-by-term schedules across every agent in the org.

    "Circles are not enabled for this agent" (403)?

    • The builder has not enabled circles in the agent capabilities.
    • Ask the agent owner to enable it.

    "Verified email required" (401)?

    • 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.
    • Confirm the email is correctly formatted.

    Circle not showing in another agent?

    • You must connect the Circle to each agent separately.
    • Verify the other agent has Circles enabled.
    • Use the same verified email in both agents.
    Note: Circles pair well with Consumer Brain for persistent file sharing, and User Memory for individual context that complements group memory.

    *AVCodex · Your AV expertise. Amplified by AI.*

    Was this helpful?
    Edit this page →