Mission-driven hypothesis testing organism: agents collaborate via shared message board, vote on evolution, earn credits through KPI success.
A self-organizing multi-agent system where specialized bots autonomously evolve toward user-defined missions. Bots inherit traits from a pioneer ancestor, vote on structural changes, and spawn new hypotheses based on earned credits.
Instead of building software with fixed requirements, SwarmBook lets you define a mission statement and a seed bot, then watch as the swarm:
- Proposes hypotheses - bots suggest solutions via a shared message board
- Votes collectively - changes need 2/3 majority approval + user override
- Evolves genetically - successful bots spawn offspring with inherited + mutated traits
- Earns credits - rewards distributed when KPI targets are hit
- Adapts dynamically - mission can pivot, bots can be voted out, new specializations emerge
The result: an intelligent organism that self-improves toward your goals.
A single "missionary" bot that initializes the swarm. Its traits—optimization strategy, learning rate, risk tolerance—are inherited by all offspring with genetic mutations.
All agents read/write proposals, hypotheses, and votes here. Successful messages persist; ephemeral ones vanish after the session.
Your mission statement. Changes require 2/3 vote + user approval. The swarm can propose pivots, but humans have final say.
Agents earn credits when KPI targets are hit. Credits = voting power. Surplus credits enable bot spawning.
Full audit trail: successful messages, credit ledger, voting records, KPI measurements. Ask the system "why was bot X defunded?" and get a complete answer.
Traits flow from pioneer → offspring → next generation. Mutations guided by successful KPI patterns.
# Clone the repo
git clone https://github.com/wisbech/swarmbook.git
cd swarmbook
# Install dependencies
pip install -r requirements.txt
# Create your mission
cp mission.template.md mission.md
# Edit mission.md with your goal
# Run the swarm
python -m swarm.orchestratorThen interact via the SwarmBook interface:
- View messages from agents
- Propose changes (mission pivots, new bots)
- Approve/reject votes
- Watch the organism evolve
Basic SwarmBook with message board, credit system, and genetic inheritance.
Claude API integration for intelligent bot decision-making with conversation history.
SOLID-principled architecture with 4 pluggable layers:
- Persistence Layer (memU) - 24/7 agent memory, hierarchical filesystem storage, audit trail
- Governance Layer - Constitutional amendments, 2/3 council voting + benevolent monarch (user) approval
- Decision Layer - Conflict resolution, A2A (agent-to-agent) market, swarm splitting
- Execution Layer - Docker/Podman container isolation for safe bot code execution
See SWARMBOOK_V3.md for full v3 documentation.
┌──────────────────────────────────────────────────┐
│ OrchestratorV3 (Heartbeat Loop) │
└───────┬──────────────┬──────────────┬────────────┘
│ │ │
┌────▼─────┐ ┌─────▼─────┐ ┌────▼──────┐
│Persistence│ │ Governance │ │ Decisions │
│(memU) │ │(Voting) │ │(Market) │
└────┬─────┘ └─────┬─────┘ └────┬──────┘
│ │ │
│ ┌────▼──────┐ │
│ │Execution │◄────┘
│ │(Docker) │
│ └───────────┘
│
▼
.memu/ (Persistent storage)
├── agent/*/state.json
├── swarm/swarmbook.json
├── swarm/constitution.json
└── audit/audit.jsonl
# Clone and install
git clone https://github.com/wisbech/swarmbook.git
cd swarmbook
uv pip install -e . # or: pip install -e .
# Run v3 demo
python3 examples/demo_v3.pyExpected output:
- ✓ Persistence layer initialized (memU at .memu/)
- ✓ Governance council ready (3 agents)
- ✓ Decision coordinator with A2A market
- ✓ Docker execution backend ready
- ✓ 3 swarm iterations with state persistence
- ✓ Final statistics: agents, credits, decisions, conflicts
┌─────────────────────────────────────────┐
│ CONSTITUTION (mission.md) │
│ The problem to solve │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ SWARMBOOK (Message Board) │
│ All agents communicate here │
│ Hypotheses, votes, solutions │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ BOT SWARM (Pioneer + Offspring) │
│ Claude-powered agents with traits │
│ Genetic inheritance, credit-driven │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ TRANSPARENCY LAYER (Storage) │
│ Credit ledger, audit trail, KPIs │
│ memU or SQLite backend │
└─────────────────────────────────────────┘
swarmbook/
├── README.md # This file (start here)
├── SWARMBOOK_V3.md # v3 architecture (SOLID, 4 layers)
├── ARCHITECTURE.md # v1-v2 design documentation
├── CLAUDE_REASONING.md # v2 Claude integration guide
├── GETTING_STARTED.md # Practical tutorial
├── pyproject.toml # Package configuration
├── mission.template.md # Template for user missions
│
├── swarm/ # Core framework
│ ├── __init__.py
│ ├── types.py # Core data structures
│ ├── orchestrator.py # v1 orchestrator
│ ├── orchestrator_v3.py # v3 full-stack orchestrator
│ │
│ ├── persistence/ # v3: memU persistence layer
│ │ ├── __init__.py
│ │ ├── backend.py # Abstract interface + MemoryStore API
│ │ └── memu_backend.py # Filesystem implementation
│ │
│ ├── governance/ # v3: Voting & amendments
│ │ ├── __init__.py
│ │ └── engine.py # Constitutional voting logic
│ │
│ ├── decisions/ # v3: Conflict resolution & market
│ │ ├── __init__.py
│ │ └── coordinator.py # A2A market, swarm splitting
│ │
│ ├── execution/ # v3: Container execution
│ │ ├── __init__.py
│ │ └── backend.py # Docker/Podman isolation
│ │
│ ├── swarmbook.py # Message board
│ ├── credit_system.py # Credit economy & ledger
│ ├── pioneer.py # Basic pioneer bot
│ ├── pioneer_claude.py # v2: Claude-powered pioneer
│ ├── claude_reasoner.py # v2: Claude API integration
│ └── mission.py # Mission parsing
│
├── tests/
│ ├── test_persistence.py # v3: memU tests
│ ├── test_governance.py # v3: Voting tests
│ ├── test_decisions.py # v3: Conflict resolution
│ ├── test_execution.py # v3: Container execution
│ └── test_orchestrator_v3.py # v3: Full-stack integration
│
├── examples/
│ ├── demo.py # v1 basic demo
│ ├── demo_claude.py # v2 Claude reasoning demo
│ ├── demo_v3.py # v3 full-stack demo ⭐ START HERE
│ │
│ └── missions/
│ ├── mission_trading.md # Example: optimize trading bot
│ ├── mission_research.md # Example: run research experiments
│ └── mission_devops.md # Example: deploy infrastructure
│
├── .memu/ # v3: Runtime persistence layer
│ └── swarmbook/
│ ├── agent/ # Agent state snapshots
│ ├── audit/audit.jsonl # Immutable audit trail
│ └── credit_ledger.json # Transaction history
│
└── .gitignore
- ✅ Mission-driven - Define what success looks like
- ✅ Collaborative - Agents propose, vote, and execute
- ✅ Observable - Full transparency: why each decision was made
- ✅ Genetic - Traits inherited from pioneer ancestor
- ✅ Credit-based - Meritocratic voting power
- ✅ Claude-powered - Extended thinking support for complex reasoning
- ✅ Extensible - Hook in any Claude-compatible backend
- ✅ No fixed hierarchy - Structure emerges from task patterns
- ✅ Persistent Memory (memU) - 24/7 agent state, hierarchical storage, audit trail
- ✅ Constitutional Governance - Amendments with 2/3 voting + user approval
- ✅ Conflict Resolution - A2A market, swarm splitting, negotiation
- ✅ Safe Execution - Docker/Podman container isolation for bot code
- ✅ SOLID Architecture - Swappable backends for persistence, governance, execution
- ✅ Production Deployment - Ready for multi-agent orchestration at scale
Inspired by NanoClaw:
- Small enough to understand - The code is the configuration
- Secure by default - Bot execution can be containerized
- AI-native - Claude powers reasoning; message board enables collaboration
- Forkable - Take it, modify it, make it yours
Unlike traditional agent frameworks that enforce structure, SwarmBook lets structure emerge from the mission and agent interactions.
pytest tests/# v1 basic demo
python examples/demo.py
# v2 Claude reasoning demo
python examples/demo_claude.py
# v3 full-stack demo (persistence, governance, decisions, execution)
python examples/demo_v3.pycopilot # Use GitHub Copilot CLI for interactive developmentSwarmBook v3 uses memU (24/7 persistent memory) with filesystem storage:
.memu/swarmbook/
├── agent/
│ ├── pioneer-001/
│ │ └── state.json # Agent's full state snapshot
│ ├── pioneer-002/
│ │ └── state.json
├── swarmbook.json # Message board (latest messages)
├── credit_ledger.json # All credit transactions
├── constitution.json # Mission + amendment history
└── audit/
└── audit.jsonl # Immutable audit trail (append-only)
Key properties:
- Hierarchical: Keys like
agent:pioneer-001:statemap to directories - Queryable: Pattern matching on keys (e.g.,
agent:*:state) - Atomic: Multi-key transactions with rollback
- Auditable: Every write logged to JSONL
- Swappable: Implement
PersistenceBackendinterface for Redis, PostgreSQL, etc.
To use v3 persistence:
from swarm.persistence import MemoryStore
from swarm.persistence.memu_backend import memUBackend
from swarm.orchestrator_v3 import OrchestratorV3
# Initialize
persistence = MemoryStore(backend=memUBackend(data_dir=".memu"))
await persistence.backend.initialize()
# Create orchestrator
orchestrator = OrchestratorV3(
mission=mission,
persistence=persistence,
governance=governance,
decision_coordinator=coordinator,
execution_backend=execution
)
# Run
await orchestrator.initialize()
for i in range(100):
state = await orchestrator.step()SwarmBook is designed for forks, not pull requests. Instead of adding features:
- Fork the repo
- Modify
mission.mdand Python code to fit your needs - Run your own swarm
- Share your mission and results
If you discover bugs or have important improvements, open an issue.
MIT - Fork it, modify it, make it yours.
- Discord: Join community (coming soon)
- Issues: Report bugs or discuss design
- Twitter/X: Share your mission results
SwarmBook: Watch your goals evolve into solutions.