# Introduction

## What is Hivemind?

**Hivemind** is a distributed AI swarm runtime. It coordinates many AI agents on complex tasks. You run multi-agent systems with a **swarm execution model**: the system breaks a task into subtasks, runs them in parallel with multiple agents, and coordinates them through a scheduler and a dependency graph.

## What Problem It Solves

- **Complex task handling** — A single agent often struggles with multi-step, branching work. Hivemind breaks a high-level goal into a DAG of subtasks and runs them with dependency-aware scheduling.
- **Parallelism** — Independent subtasks run at the same time. You set the worker count. Wall-clock time stays low.
- **Context and memory** — Agents share a memory store (episodic, semantic, research, artifact) and a knowledge graph. Later tasks use what earlier tasks learned.
- **Observability** — A structured event log supports replay, telemetry, and debugging. You don’t change runtime behavior to inspect it.

## Core Concepts

| Concept | Description |
|--------|-------------|
| **Planner** | Turns one high-level task into an ordered list of subtasks (and can expand the plan as tasks finish). |
| **Scheduler** | Keeps a DAG of tasks and reports which ones are ready to run (dependencies met). |
| **Executor** | Runs ready tasks with a worker pool of agents and enforces concurrency limits. |
| **Agent** | A stateless LLM worker. It runs one task (and can use tools and memory). |
| **Swarm** | The single entrypoint: `Swarm().run("your task")` wires planner, scheduler, and executor and returns results. |

## Why Swarm Execution Matters

- **Scalability** — Add workers to run more subtasks in parallel.
- **Robustness** — A failure or retry affects one task. The DAG and scheduler keep the rest of the run consistent.
- **Composability** — Tools, memory, and the knowledge graph use the same task and event model. You can build pipelines (research, codebase analysis, experiments) on the same runtime.

## High-Level Overview

1. You give the swarm a **user task** (e.g. “Analyze diffusion models and write a one-page summary”).
2. The **Planner** uses an LLM to break it into **subtasks** (e.g. five steps) and emits `task_created` events.
3. The **Scheduler** builds a **DAG** from those subtasks and their dependencies.
4. The **Executor** takes **ready** tasks, runs each with an **Agent** (optionally with tools and memory), and marks them completed.
5. Optionally, **adaptive planning** adds new subtasks when a task completes.
6. **Results** are collected. Optionally, swarm memory and the knowledge graph are updated for future runs.

Everything runs **locally** with minimal setup. No distributed cluster. You configure via environment variables and/or TOML: `hivemind.toml` or `workflow.hivemind.toml` in the project, or `~/.config/hivemind/config.toml`, or legacy `.hivemind/config.toml`. Run predefined **workflows** from `workflow.hivemind.toml` with `hivemind workflow <name>`. Use the **SDK** with `Swarm(config="hivemind.toml")` for a config-driven swarm.
