AICoven Tutorial: Covens, Keys, Roles, Orchestration & Memory

2. Add Your Provider Keys (BYOK)

Before covens can really shine, you connect your own AI providers.

2.1 Why keys?

AICoven doesn't resell models. You bring your own:

• OpenAI (GPT-4, GPT-4o, etc.)
• Anthropic (Claude)
• Google Gemini
• Others (Mistral, etc.)

This keeps billing, data retention, and model choice under your control.

2.2 How to add a key

1. Go to Settings → Provider Keys (or the FTUE “Connect Your AI Providers” step).
2. Tap Add Provider Key.
3. Choose a provider (for example, OpenAI).
4. Fill:
   • Display Name – how you'll recognize this key (for example, OpenAI – Prod, Claude – Personal).
   • API Key – paste your key from the provider's dashboard.
5. Save. AICoven will:
   • Store the key encrypted at rest.
   • Run a quick health check and pull supported models.

2.3 Important security note

• Your keys are encrypted and only decrypted in memory when needed.
• If you lose the encryption keys, your data may not be recoverable. That's why the FTUE emphasizes key safety rather than “end-to-end” claims.
• Treat provider keys like passwords to your AI accounts.

2.4 Tips

• Use different keys (or separate accounts/projects) for:
  • Personal experiments
  • Team / production work
• Give each key a clear display name:Team – Use, Env – Project.

3. Creating Your First Coven

Once at least one provider key is healthy:

4. Adding & Managing Roles (Agents)

Roles are the core of orchestration: each role is an AI agent with:

• A name and emoji (identity)
• A model and provider key
• A system prompt (persona and instructions)
• Optional tools and budgets

4.1 Creating a role

1. Inside a coven, open Roles (Agent Roles) for that coven.
2. Tap Add Role.
3. Configure:
   • Name & Emoji – for example:
     • 🧠 Strategist
     • 🧾 Scribe
     • 👩‍💻 Coder
   • Model & Provider – pick from your healthy provider accounts.
   • Prompt / Description – what it does and how (for example, “You are a product strategist focused on go-to-market plans …”).
   • Temperature / Max tokens – control creativity and verbosity.
   • Tools (if enabled) – GitHub, Google Docs, Sheets, Calendar, etc.
   • Budget / usage hints – if exposed, keep expensive models reserved for critical roles.
4. Save. The role becomes available in the role picker in threads, @mentions and Roundtable flows, and memory scoping (agent-specific memory).

4.2 Role design tips

• Start with three core roles per coven:
  • Planner / Strategist – plans, roadmaps, specs.
  • Executor / Coder / Analyst – does concrete work.
  • Scribe / Editor – cleans up, documents, and organizes.
• Use cheaper models for exploratory chat, brainstorming, and draft notes.
• Use premium models for final copy, coding tasks, complex reasoning, and critical analysis.

5. Threads, Conversations & Orchestration

5.1 Threads

A thread is a conversation inside a coven:

• Often maps to a task, spec, or sub-project.
• Can have a primary role (who owns the conversation).
• Shows history, memory interactions, and model usage.

1. Inside a coven, tap New Thread.
2. Pick a role (or use the default assistant).
3. Optionally set auto-route / default behaviors.

5.2 Primary role vs @mentions

• Primary role: the default agent responding in that thread.
• @mentions: bring in other agents ad-hoc without changing the primary.

Examples:

• @Coder to implement a change while Strategist remains primary.
• @Scribe to summarize a long discussion.

5.3 Agents talking to each other

The system is designed so agents can:

• See the same thread context (subject to permissions).
• Respond to each other's outputs when you @mention multiple roles or use Roundtable or Forward to Role.

Typical patterns:

• Roundtable: ask 2–3 roles the same question, compare answers side-by-side, and optionally reconcile into a single plan.
• Forward to Role / Handoff: “@Planner, finalize this plan and hand it off to @Coder.” The platform creates a linked sub-thread so Coder continues with context.

6. Model Availability & Routing

Behind the scenes, each role knows which provider account it uses, which models are available, and any optional fallback routes.

6.1 Basic routing

1. The system checks the role's preferred model (for example, claude-3.5-sonnet).
2. It also knows which provider account / API key to use.
3. If the call fails or hits a budget cap, it can fall back to a secondary model (for example, gpt-4.1-mini) and surface this as a breadcrumb in the UI (for example, Claude → GPT).

6.2 Tips for routing

• Give critical roles at least one backup model on another provider (for example, Planner: Claude → GPT-4o, Coder: GPT-4.1 → Claude).
• Use separate provider accounts for experimental vs production usage.
• Watch the model badges in chat to understand which models actually executed.

7. Memory: What Agents Remember

AICoven uses a memory fabric with clear scopes:

• Agent memory – private to a role (its preferences, working style).
• User memory – personal notes about you.
• Coven memory – project-shared knowledge (requirements, docs, decisions).

7.1 How memory is written

1. During chat, agents propose memory events (for example, “We should remember X”).
2. These go into memory_events as proposed.
3. You (or a policy) approve them from memory chips in the thread or from the Memory Explorer UI.
4. Approved entries become searchable memory chunks.

7.2 How memory is read

1. When you send a message, the memory service looks at the thread, coven, user, and agent scopes and searches for top-k relevant chunks (vector + keyword + tags).
2. The system builds a context sandwich: system prompt (role config), retrieved memory snippets, recent thread messages, and your new message.
3. This gives each reply grounded context without you pasting huge prompts every time.

7.3 Memory tips

• Use tags (if available) like #requirements, #decisions, #risk.
• Regularly review proposed writes in Memory Explorer – approve the truly reusable pieces and reject ephemeral or logistical stuff.
• Keep agent prompts short; let memory carry project details.

8. Putting It All Together: Example Flow

Here's a concrete “happy path” using all the pieces: