zo-swarm-orchestrator

Category: Tools & Productivity | Uploader: marlandoj | Downloads: 0 | Version: v1.0（Latest）

Spawn parallel agent teams with token optimization, hierarchical memory, and resilient execution. v4 adds token-aware memory strategies to prevent context window exhaustion.

Changelog: Source: GitHub https://github.com/marlandoj/zo-swarm-orchestrator

Directory Structure

Current level: Root

📁 assets/
- 📄 persona-registry.json 3.8 KB
- 📄 swarm-patterns.json 3.3 KB
📁 examples/
- 📄 ffb-marketing-campaign.json 10.4 KB
- 📄 ffb-quick-wins.json 8.0 KB
- 📄 foreign-markets-analysis.json 1.8 KB
- 📄 foreign-markets-financial-focus.json 2.3 KB
- 📄 sample-tasks.json 410 B
- 📄 security-engineer-update-tasks.json 7.6 KB
- 📄 test-10-agents-stress.json 3.7 KB
- 📄 test-20-agents-stress.json 5.4 KB
- 📄 test-5-agents-stress.json 2.2 KB
- 📄 test-composite-router.json 1.9 KB
- 📄 test-v4-simple.json 806 B
- 📄 v3-follow-up-tasks.json 1.2 KB
- 📄 v3-memory-tasks.json 2.1 KB
- 📄 v3-persona-memory-bridge.json 458 B
- 📄 website-review-auto.json 3.4 KB
- 📄 website-review-hermes.json 4.9 KB
- 📄 website-review-jhf.json 6.5 KB
- 📄 website-review-zo-api.json 5.0 KB
- 📄 website-review.json 4.9 KB
📁 scripts/
- 📄 benchmark.ts 11.8 KB
- 📄 claude-code-bridge.sh 2.0 KB
- 📄 export-pdf.sh 2.8 KB
- 📄 inter-agent-comms.ts 13.4 KB
- 📄 orchestrate-v4.ts 103.6 KB
- 📄 performance-test.ts 21.5 KB
- 📄 swarm 1.2 KB
- 📄 swarm-config.ts 6.7 KB
- 📄 swarm-memory.ts 20.9 KB
- 📄 swarm-status.ts 5.5 KB
- 📄 test-orchestrator.ts 5.7 KB
- 📄 token-optimizer.ts 11.2 KB
📄 .gitignore 425 B
📄 AGENTS.md 6.6 KB
📄 bun.lock 1.2 KB
📄 CLAUDE.md 2.4 KB
📄 COMPOSITE_ROUTER_DESIGN.md 18.5 KB
📄 config.json 535 B
📄 index.ts 30 B
📄 package.json 208 B
📄 README.md 12.3 KB
📄 SKILL.md 9.2 KB
📄 tsconfig.json 713 B

SKILL.md

---
name: zo-swarm-orchestrator
description: Spawn parallel agent teams with token optimization, hierarchical memory, and resilient execution. v4 adds token-aware memory strategies to prevent context window exhaustion.
metadata:
  created: 2026-02-08
  updated: 2026-03-01
  version: 4.3.0
---
# Swarm Orchestrator Skill v4.3.0

A reusable skill that enables **any persona** to spawn parallel agent teams, delegate tasks across specialized personas, and synthesize results into coherent output.

**v4.3 "Hivemind Routing":** Semantic-aware composite routing that distributes work across all executors based on capability matching, health signals, complexity fit, and execution history. The swarm collectively learns which agent is best for each type of task.

---

## ⚡ Quick Start (Use v4)

```bash
cd Skills/zo-swarm-orchestrator/scripts

# Recommended: v4 with hierarchical memory
bun orchestrate-v4.ts examples/test-v4-simple.json --swarm-id my-project

# Cost-optimized: no memory
bun orchestrate-v4.ts tasks.json --strategy none

# Bounded context: sliding window
bun orchestrate-v4.ts tasks.json --strategy sliding --max-tokens 8000

# Health check
bun orchestrate-v4.ts doctor
```

---

## Version Status

| Version | Status | Key Innovation |
|---------|--------|----------------|
| **v4.3** | ✅ **Current** | **Hivemind Routing** — semantic synonym matching, flattened affinity matrix, adaptive executor distribution |
| v4.2 | ✅ Current | Composite router, retry-with-reroute, executor history, routing strategies |
| v4.1 | ✅ Current | DAG dependencies, NDJSON logging, inter-agent messaging |
| v4.0 | ✅ Current | Hierarchical memory, token budgets, pre-warm caching |
| v1–v3 | Archived | Superseded by v4 |

---

## Version 4 - Token-Optimized Hierarchical Memory

Building on v3's persistent memory, **v4 introduces intelligent memory strategies** that automatically manage token budgets to prevent the context window exhaustion that caused v1 failures.

### The Problem v4 Solves

From February 2026 production failures:
- **Context window exhaustion**: 5 agents × 256k tokens = system failure
- **Unbounded memory growth**: Sequential memory grows forever
- **No token budgeting**: No visibility into prompt token usage

### What v4 Adds

| Feature | Implementation | Benefit |
|---------|----------------|---------|
| **Token cleaning** | HTML stripping, deduplication, normalization | ~10-15% token reduction |
| **Hierarchical memory** | Working memory + long-term memory retrieval | Bounded context, relevant history |
| **Sliding window** | Fixed-size recent context window | Predictable token usage |
| **Token budgets** | Configurable max tokens per context | Never exceed context limits |
| **Strategy selection** | Choose memory strategy per task | Optimize for cost vs. context |

---

## Memory Strategies

### Comparison

| Strategy | Token Efficiency | Context Quality | Best For |
|----------|------------------|-----------------|----------|
| `none` | ⭐⭐⭐⭐⭐ | ⭐☆☆☆☆ | Independent tasks, cost-sensitive |
| `sliding` | ⭐⭐⭐⭐☆ | ⭐⭐⭐☆☆ | Recent context matters |
| `hierarchical` | ⭐⭐⭐⭐☆ | ⭐⭐⭐⭐⭐ | Complex multi-step workflows |
| `sequential` | ⭐☆☆☆☆ | ⭐⭐⭐⭐⭐ | Debugging, small swarms only |

### Benchmark Results

```
Strategy       Avg Prompt    Memory    Token
               Tokens        Items     Savings
───────────────────────────────────────────────
none           26            0         -93%
sliding        356           3         -8%
hierarchical   416           4         -8%
sequential     386           5         0%
```

---

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--swarm-id <id>` | Unique swarm identifier | auto-generated |
| `--strategy <type>` | Memory strategy | hierarchical |
| `--max-tokens <n>` | Token budget for context | 8000 |
| `--concurrency <n>` | Max parallel API agents | 5 |
| `--local-concurrency <n>` | Max parallel local executors | 4 |
| `--timeout <seconds>` | Per-task timeout | 300 |
| `--model <name>` | Model name for API calls | from env |
| `--dag-mode <mode>` | `streaming` or `waves` | streaming |
| `--routing-strategy <s>` | `fast`, `reliable`, `balanced`, or `explore` | balanced |
| `--no-memory` | Disable all memory | false |

---

## Task File Format (v4)

```json
[
  {
    "id": "task-1",
    "persona": "frontend-developer",
    "task": "Analyze UI/UX for accessibility issues",
    "priority": "high",
    "memoryStrategy": "hierarchical",
    "outputToMemory": true,
    "memoryMetadata": {
      "category": "ui-analysis",
      "priority": "high",
      "tags": ["accessibility", "responsive"]
    }
  }
]
```

---

## Files Reference

| File | Purpose |
|------|---------|
| `orchestrate-v4.ts` | Main orchestrator |
| `token-optimizer.ts` | Token cleaning + hierarchical memory |
| `swarm-memory.ts` | SQLite persistence + inter-agent messaging |
| `swarm-config.ts` | Configuration management CLI |
| `benchmark.ts` | Memory strategy benchmarking |
| `test-orchestrator.ts` | Test suite |
| `performance-test.ts` | Baseline vs enhanced performance test |

---

## Local Executors

Tasks assigned to `claude-code`, `hermes`, `gemini`, or `codex` personas are routed to **local executor bridges** instead of the API. The bridge scripts, registry, and tooling live in the companion skill [`zo-swarm-executors`](../zo-swarm-executors/):

| Executor | Bridge | Speed | Strengths |
|----------|--------|-------|-----------|
| `claude-code` | `claude-code-bridge.sh` | ~25-120s | Complex multi-file changes, codebase-aware analysis, git operations |
| `hermes` | `hermes-bridge.sh` | ~15-60s | Web research, security audits, multi-tool investigation, data gathering |
| `gemini` | `gemini-bridge.sh` | ~2-12s (daemon) | Large-context analysis (1M+ tokens), multimodal, cross-validation |
| `codex` | `codex-bridge.sh` | ~3s | Fast code generation, shell commands, rapid prototyping |

```
Skills/zo-swarm-executors/
├── bridges/          # claude-code, hermes, gemini, codex bridge scripts
├── registry/         # executor-registry.json
├── scripts/          # doctor.ts, register.ts, test-harness.ts, gemini-daemon.ts
└── docs/             # BRIDGE_PROTOCOL.md, identity references
```

The orchestrator discovers executors automatically via `persona-registry.json` (entries with `"executor": "local"`). Override the executor registry path with `SWARM_EXECUTOR_REGISTRY`.

See [`zo-swarm-executors/README.md`](../zo-swarm-executors/README.md) for bridge protocol, adding custom executors, and health checks.

---

## Utilities

```bash
# Benchmark all memory strategies
bun benchmark.ts

# Test orchestrator
bun test-orchestrator.ts

# Memory management
bun swarm-memory.ts stats
bun swarm-memory.ts list-sessions
bun swarm-memory.ts cleanup 30
```

---

## Configuration

You can configure the orchestrator using **either** a config file **or** environment variables.

### Option 1: Config File (Recommended)

Create `config.json` in the skill root:

```json
{
  "maxConcurrency": 5,
  "localConcurrency": 4,
  "timeoutSeconds": 300,
  "maxRetries": 3,
  "memory": {
    "enable": true,
    "workingMemorySize": 2,
    "longTermMemorySize": 3,
    "enableDeduplication": true,
    "enableHTMLStripping": true,
    "maxTokens": 8000
  }
}
```

**Priority:** CLI flags > Config file > Environment variables > Defaults

### Option 2: Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ANTHROPIC_API_KEY` | Anthropic API key (preferred) | — |
| `ZO_CLIENT_IDENTITY_TOKEN` | Zo API auth (fallback) | — |
| `SWARM_WORKSPACE` | Root for deployment resources | `/home/workspace` |
| `SWARM_MAX_CONCURRENCY` | Max parallel API agents | 2 |
| `SWARM_LOCAL_CONCURRENCY` | Max parallel local executors | 4 |
| `SWARM_TIMEOUT_SECONDS` | Per-task timeout | 300 |
| `SWARM_MAX_RETRIES` | Retry attempts | 3 |
| `SWARM_IDENTITY_DIR` | Persona identity files directory | `$SWARM_WORKSPACE/IDENTITY` |
| `SWARM_SOUL_FILE` | Path to constitution file | `$SWARM_WORKSPACE/SOUL.md` |
| `SWARM_PERSONA_MEMORY_DIR` | Persona-specific memory files | `$SWARM_WORKSPACE/.zo/memory/personas` |
| `SWARM_MEMORY_SCRIPT` | Memory search script path | `$SWARM_WORKSPACE/.zo/memory/scripts/memory.ts` |
| `SWARM_AGENT_REGISTRY` | Persona registry JSON path | `$SWARM_WORKSPACE/agency-agents-personas.json` |
| `SWARM_EXECUTOR_REGISTRY` | Local executor registry JSON path | `Skills/zo-swarm-executors/registry/executor-registry.json` |

---

## Roadmap

Planned optimizations from production profiling (see README.md for full details):

| Phase | Optimizations | Expected Savings |
|-------|--------------|------------------|
| **Phase 1** — Quick Wins | O3: Pre-warm cache TTL, O4: Prompt format constraints, O6: Circuit breaker tuning | 5-13% |
| **Phase 2** — Execution Engine | O2: DAG streaming improvements, O1: Request batching | +13-30% |
| **Phase 3** — Refinements | O5: Early filtering, O7: Output deduplication, O8: Concurrent caching | +2-5% |

---

## References

- Prompt-Refiner: https://github.com/JacobHuang91/prompt-refiner
- Agent-Memory-Playground: https://github.com/AIAnytime/Agent-Memory-Playground

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

zo-swarm-orchestrator

Directory Structure

SKILL.md

Report

Notice