@context-engine-ai/swarm

Experimental multi-agent swarm that runs on top of the context-engine knowledge base.

A run is plan → research → synthesize → reflect:

                       goal
                        │
                   ┌────▼────┐
                   │ planner │  decomposes into independent subtasks
                   └────┬────┘
          ┌─────────────┼─────────────┐
     ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐
     │researcher│  │researcher│  │researcher│   parallel; each one calls
     └────┬─────┘  └────┬─────┘  └────┬─────┘   retrieve + record_finding
          │   findings blackboard     │
          └─────────────┼─────────────┘
                  ┌─────▼──────┐
                  │synthesizer │  merges reports into one answer
                  └─────┬──────┘
                        │
                   POST /reflect   the run is distilled into session memory,
                                   so future sessions can retrieve it

The swarm talks to the engine only over its public HTTP API (/retrieve, /reflect) — same boundary as the MCP server and hooks. It never imports engine internals.

Providers

The agent loop is provider-agnostic (src/providers/types.ts). Two implementations ship:

| Provider | Default model | Notes | |-------------|-------------------|-------| | anthropic | claude-opus-4-8 | Requires ANTHROPIC_API_KEY. Adaptive thinking enabled. | | ollama | qwen3 | Local, free. Model must support tool calling (qwen3, qwen2.5, llama3.1, …). |

Selection: --provider/--model flags → SWARM_PROVIDER/SWARM_MODEL env → anthropic if ANTHROPIC_API_KEY is set, otherwise ollama.

Usage

npm run build

# local qwen via ollama
SWARM_PROVIDER=ollama SWARM_MODEL=qwen3 \
  node packages/swarm/dist/index.js "how does retrieval scoring work?"

# claude
SWARM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-... \
  node packages/swarm/dist/index.js -w payments "trace a refund end to end"

Progress streams to stderr; the synthesized answer goes to stdout. Each run gets a swarm-<uuid> session ID, visible in the engine's observability logs and (after reflection) in session memory.

Environment

| Variable | Default | Purpose | |---|---|---| | CONTEXT_ENGINE_URL | http://localhost:3333 | Engine API base URL | | CONTEXT_ENGINE_API_KEY | — | Bearer token if the engine sets API_KEY | | SWARM_PROVIDER | auto | anthropic | ollama | | SWARM_MODEL | per provider | Model name | | ANTHROPIC_API_KEY | — | Anthropic provider | | OLLAMA_URL | http://localhost:11434 | Ollama provider |

Adding a provider

Implement ChatProvider (src/providers/types.ts) — one chat() method mapping the neutral message/tool format onto your wire format — and register it in createProvider() (src/providers/index.ts). The providerData passthrough on assistant messages lets a provider round-trip native payloads (e.g. Anthropic thinking blocks) without the agent loop knowing about them.