HIVE

Swarm Management

Context Blocks

Context Blocks

Context blocks are the shared memory of your swarm—persistent knowledge that every agent can access throughout a conversation. They enable agents to work from the same information, maintain consistency, and avoid repeatedly asking for the same details.

This guide covers everything about context blocks: what they are, when to use them, how to structure them effectively, and best practices for keeping your agents informed without overwhelming them.

Understanding Context Blocks

What Are Context Blocks?

Context blocks are persistent pieces of information attached to a swarm. Unlike conversation messages that flow by, context blocks remain accessible to all agents throughout the swarm's lifetime.

┌─────────────────────────────────────────────────────────────────────┐
│                         CONTEXT ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │                    AGENT PROMPT CONSTRUCTION                │    │
│  ├────────────────────────────────────────────────────────────┤    │
│  │                                                            │    │
│  │  1. SYSTEM PROMPT (agent identity & behavior)              │    │
│  │     ↓                                                      │    │
│  │  2. CONTEXT BLOCKS (sorted by priority)                    │    │
│  │     ├── Critical: Project Requirements                     │    │
│  │     ├── High: Tech Stack, Style Guide                      │    │
│  │     ├── Medium: Meeting Notes                              │    │
│  │     └── Low: Reference Materials                           │    │
│  │     ↓                                                      │    │
│  │  3. CONVERSATION HISTORY (recent messages)                 │    │
│  │     ↓                                                      │    │
│  │  4. CURRENT USER MESSAGE                                   │    │
│  │                                                            │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  All agents in the swarm see the same context blocks               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Why Context Blocks Matter

Without Context BlocksWith Context Blocks
Must repeat information each messageInformation persists automatically
Agents may give inconsistent answersAll agents work from same facts
Context gets lost in long conversationsCritical info always accessible
Users must remember what agents knowShared knowledge is explicit

Context vs. Conversation

Understanding the difference:

CONTEXT BLOCKS                    CONVERSATION MESSAGES
─────────────────────────────────────────────────────────
Persistent                        Ephemeral
Structured reference              Dynamic discussion
Set up front                      Emerges naturally
Same for all agents               Sequential flow
Background knowledge              Active dialogue

Creating Context Blocks

Via the Dashboard

  1. Open a swarm you want to add context to
  2. Look for the Context panel (usually in the right sidebar or settings)
  3. Click Add Context Block or the + button
  4. Fill in the context block form:
┌─────────────────────────────────────────────────────────────┐
│                    ADD CONTEXT BLOCK                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name *                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Project Requirements                                 │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Priority                                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ● Critical  ○ High  ○ Medium  ○ Low                 │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Content *                                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ # Mobile App Requirements                           │   │
│  │                                                      │   │
│  │ ## Core Features                                     │   │
│  │ - User authentication (OAuth + email)               │   │
│  │ - Push notifications                                │   │
│  │ - Offline support with sync                         │   │
│  │                                                      │   │
│  │ ## Technical Constraints                            │   │
│  │ - Must support iOS 14+ and Android 10+             │   │
│  │ - Bundle size under 50MB                           │   │
│  │ - Battery optimization required                     │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ☑ Shared with all agents                                  │
│                                                             │
│                              [Cancel]  [Add Context]        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Context Block Fields

FieldRequiredDescription
NameYesClear identifier (appears in UI and agent prompts)
PriorityYesDetermines prompt ordering and agent attention
ContentYesThe actual information (supports Markdown)
SharedNoWhether all agents can see it (default: yes)

Priority System

Priority determines how prominently context appears in agent prompts and how much attention agents pay to it.

Priority Levels Explained

┌─────────────────────────────────────────────────────────────────────┐
│                        PRIORITY HIERARCHY                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  CRITICAL ████████████████████████████████████████████████████████ │
│  • Appears first in context                                         │
│  • Agents reference this continuously                               │
│  • Information that MUST be followed                                │
│  • Example: Compliance requirements, core constraints               │
│                                                                     │
│  HIGH ██████████████████████████████████████████                   │
│  • Appears early in context                                         │
│  • Agents frequently consider this                                  │
│  • Important reference information                                  │
│  • Example: Tech stack, style guides                                │
│                                                                     │
│  MEDIUM ████████████████████████████                               │
│  • Appears in middle of context                                     │
│  • Referenced when relevant                                         │
│  • Helpful background information                                   │
│  • Example: Meeting notes, decisions history                        │
│                                                                     │
│  LOW ████████████████                                              │
│  • Appears later in context                                         │
│  • Referenced occasionally                                          │
│  • Nice-to-know information                                         │
│  • Example: Reference links, glossaries                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Priority Selection Guide

PriorityUse WhenExamples
CriticalAgents MUST follow thisLegal requirements, safety constraints, core project rules
HighAgents should strongly considerTechnical specs, style guides, key decisions
MediumHelpful backgroundMeeting notes, context history, rationale
LowReference if neededGlossaries, external links, nice-to-know

Common Mistake: Making everything Critical. When everything is critical, nothing is. Reserve Critical for truly non-negotiable information.

Context Block Templates

Requirements Document

Name: Project Requirements
Priority: Critical

# [Project Name] Requirements

## Overview
[One paragraph describing what we're building and why]

## Must-Have Features
- Feature 1: [brief description]
- Feature 2: [brief description]
- Feature 3: [brief description]

## Nice-to-Have Features
- Feature A: [brief description]
- Feature B: [brief description]

## Constraints
- Deadline: [date]
- Budget: [amount or "flexible"]
- Technical: [any technical limitations]

## Success Criteria
- [How we'll measure success]

Technical Specification

Name: Technical Specification
Priority: High

# Tech Stack

## Frontend
| Technology | Version | Purpose |
|------------|---------|---------|
| React | 18.x | UI framework |
| TypeScript | 5.x | Type safety |
| Tailwind CSS | 3.x | Styling |

## Backend
| Technology | Version | Purpose |
|------------|---------|---------|
| Node.js | 20.x | Runtime |
| PostgreSQL | 15.x | Database |
| Redis | 7.x | Caching |

## Infrastructure
- Hosting: [provider]
- CI/CD: [tool]
- Monitoring: [tool]

## Coding Standards
- Use ESLint with Airbnb config
- Prefer functional components
- Write unit tests for business logic

Brand & Style Guide

Name: Brand Style Guide
Priority: High

# Brand Voice & Style

## Voice Characteristics
- **Professional**: Knowledgeable, trustworthy
- **Approachable**: Friendly, not corporate
- **Clear**: Direct, jargon-free

## Writing Rules
1. Use active voice
2. Keep sentences under 20 words
3. Lead with the benefit
4. Use "you" to address users

## Terminology
| Use | Don't Use |
|-----|-----------|
| user | customer, client |
| select | click, tap |
| dashboard | control panel |
| sign in | log in, login |

## Tone Examples
- Welcome message: "Welcome back! Here's what's new."
- Error message: "Something went wrong. Let's fix it together."
- Success message: "Done! Your changes are saved."

API Documentation

Name: API Reference
Priority: High

# API Documentation

## Base URL
\`https://api.example.com/v1\`

## Authentication
All requests require Bearer token:
\`Authorization: Bearer <token>\`

## Key Endpoints

### Users
- \`GET /users\` - List users
- \`POST /users\` - Create user
- \`GET /users/:id\` - Get user details

### Products
- \`GET /products\` - List products (supports pagination)
- \`GET /products/:id\` - Get product details

## Error Codes
| Code | Meaning |
|------|---------|
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Server error |

## Rate Limits
- 100 requests per minute per user
- 1000 requests per hour per user

Decision Log

Name: Key Decisions
Priority: Medium

# Decision Log

## Architecture Decisions

### 2024-01-15: Database Choice
**Decision:** Use PostgreSQL over MongoDB
**Rationale:** Relational data model fits our needs; team has SQL expertise
**Status:** Approved

### 2024-01-20: Authentication
**Decision:** Implement OAuth 2.0 with JWT tokens
**Rationale:** Industry standard, supports SSO expansion
**Status:** Approved

## Product Decisions

### 2024-01-22: Pricing Model
**Decision:** Tiered pricing (Free, Pro, Enterprise)
**Rationale:** Allows self-service growth with enterprise upsell
**Status:** Under review

## Open Questions
- [ ] Mobile app: Native vs React Native?
- [ ] Analytics: Build vs buy?

Customer Personas

Name: Customer Personas
Priority: Medium

# Target User Personas

## Primary: "Technical Tom"
- **Role:** Senior Developer
- **Age:** 28-40
- **Goals:** Ship code faster, reduce bugs
- **Pain Points:** Too many tools, context switching
- **Quote:** "I just want something that works and gets out of my way."

## Secondary: "Manager Maria"
- **Role:** Engineering Manager
- **Age:** 32-45
- **Goals:** Team visibility, project tracking
- **Pain Points:** Reporting overhead, unclear status
- **Quote:** "I need to know where we stand without interrupting my team."

## Tertiary: "Startup Steve"
- **Role:** Solo Founder
- **Age:** 25-35
- **Goals:** Move fast, wear many hats
- **Pain Points:** Limited budget, no dedicated team
- **Quote:** "I need enterprise features at startup prices."

Meeting Notes Template

Name: Sprint 23 Planning
Priority: Medium

# Sprint 23 Planning - January 15, 2024

## Attendees
Product, Engineering, Design

## Decisions Made
1. **Priority 1:** Complete user onboarding flow
2. **Priority 2:** Fix performance issues on dashboard
3. **Deprioritized:** Dark mode (moved to Sprint 25)

## Key Discussion Points
- Onboarding should be < 5 steps
- Dashboard must load in < 2 seconds
- Consider A/B testing welcome email

## Action Items
- [ ] @Engineering: Performance audit by Jan 17
- [ ] @Design: Onboarding wireframes by Jan 18
- [ ] @Product: Write acceptance criteria by Jan 16

## Next Meeting
January 22, 2024 @ 10am

Glossary

Name: Terminology Glossary
Priority: Low

# Project Glossary

## Business Terms
| Term | Definition |
|------|------------|
| MRR | Monthly Recurring Revenue |
| ARR | Annual Recurring Revenue |
| Churn | Users who cancel subscription |
| NPS | Net Promoter Score |

## Technical Terms
| Term | Definition |
|------|------------|
| API | Application Programming Interface |
| JWT | JSON Web Token |
| SSO | Single Sign-On |
| CDN | Content Delivery Network |

## Internal Terms
| Term | Definition |
|------|------------|
| Tiger Team | Cross-functional sprint team |
| Ship Week | Quarterly release milestone |
| Code Red | Critical production issue |

Managing Context Effectively

When to Update Context

Update context blocks when:

✓ Requirements change
✓ New decisions are made
✓ Technical specs evolve
✓ Team agreements change
✓ Important meetings occur
✓ Information becomes outdated

Updating Process

  1. Navigate to the context block
  2. Click Edit (pencil icon)
  3. Make your changes
  4. Add a brief note about what changed (optional)
  5. Save changes

All agents immediately see updated context - no need to restart conversations.

Version History Tip

For important context, maintain change history within the block:

# Project Requirements

## Current Version (v3 - Jan 20)
[Current requirements here]

## Change History
- **v3 (Jan 20):** Added mobile support requirement
- **v2 (Jan 10):** Removed payment gateway (descoped)
- **v1 (Jan 1):** Initial requirements

Archiving Old Context

When context is no longer relevant:

OptionWhen to Use
DeleteInformation is completely obsolete
Set to Low priorityMight be useful for reference
UnshareKeep for yourself but hide from agents

Context Block Best Practices

1. Keep It Concise

Agents process context more effectively when it's focused:

GOOD:
# Tech Stack
- Frontend: React 18 + TypeScript
- Backend: Node.js + PostgreSQL
- Hosting: Vercel + AWS

BAD:
[50 pages of detailed documentation that includes
installation guides, troubleshooting, history,
alternative considerations, etc.]

Rule of Thumb: If a context block exceeds 500 words, consider splitting it or summarizing.

2. Structure for Scanning

Use clear formatting that agents (and humans) can quickly parse:

# Clear Header

## Section with Purpose
- Bullet points for lists
- Keep items brief
- One idea per bullet

## Another Section
| Tables | Work | Well |
|--------|------|------|
| For    | Data | Lists|

## Key Takeaway
**Bold the most important point**

3. Be Specific, Not Vague

GOOD:
"Response time must be under 200ms for API calls"

BAD:
"The system should be fast"
GOOD:
"Use American English spelling (e.g., 'color' not 'colour')"

BAD:
"Write correctly"

4. Prioritize Correctly

Ask yourself: "If an agent ignores this, what happens?"

  • Disaster (compliance failure, security breach) → Critical
  • Poor quality output → High
  • Missed opportunity → Medium
  • Minor inconsistency → Low

5. Remove Stale Information

Old context can actively mislead agents:

Schedule a monthly context review:
1. Is this information still accurate?
2. Is it still relevant to current work?
3. Has anything changed that should be reflected?
4. Can anything be removed or consolidated?

6. Avoid Duplication

If information exists in multiple places, it will become inconsistent:

Instead of:
- Requirements doc with tech stack
- Separate tech stack doc
- Meeting notes mentioning tech stack

Consolidate to:
- Requirements doc (business requirements only)
- Tech stack doc (single source of truth)
- Meeting notes reference tech stack doc

Advanced Context Patterns

Layered Context

For complex projects, organize context in layers:

Layer 1 (Critical): Core constraints
  └── "What we MUST do / CANNOT do"

Layer 2 (High): Implementation guidance
  └── "How we should do things"

Layer 3 (Medium): Background
  └── "Why we made these choices"

Layer 4 (Low): Reference
  └── "Where to find more information"

Dynamic Context for Different Phases

Update context as projects evolve:

Discovery Phase:
  - User research findings
  - Competitive analysis
  - Problem definition

Design Phase:
  - Design system
  - User flows
  - Wireframes reference

Development Phase:
  - Technical specification
  - API contracts
  - Coding standards

Launch Phase:
  - Go-live checklist
  - Support escalation
  - Monitoring alerts

Agent-Specific Context

While most context is shared, you can create context visible only to specific agents:

Global Context (all agents):
  - Project requirements
  - Brand guidelines

Developer-specific:
  - Detailed API docs
  - Code review checklist

Writer-specific:
  - Content calendar
  - SEO guidelines

Troubleshooting Context Issues

Agents Ignoring Context

Symptoms: Agents give answers that contradict context

Solutions:

  • Move to higher priority
  • Make the instruction more explicit
  • Break into smaller, clearer blocks
  • Check for contradictions with other context

Context Too Long

Symptoms: Responses feel generic, slow processing

Solutions:

  • Summarize verbose sections
  • Split into multiple focused blocks
  • Remove redundant information
  • Lower priority of less essential info

Contradictory Context

Symptoms: Agents give inconsistent answers

Solutions:

  • Audit all context blocks for conflicts
  • Establish single source of truth
  • Remove duplicate information
  • Update all blocks when things change

Next Steps

Now that you understand context blocks:

  • [Human-in-the-Loop](/docs/swarms/human-in-loop): Control how you interact with the swarm
  • [Creating Swarms](/docs/swarms/creating-swarms): Design swarms that use context effectively
  • [Communication Patterns](/docs/swarms/communication-patterns): How agents use context in conversation

Next

Human-in-the-Loop

Cookie Preferences

We use cookies to enhance your experience, analyze site traffic, and for marketing purposes. By clicking "Accept All", you consent to our use of cookies. Read our Privacy Policy for more information.