CYCGRAPH is an orchestration engine for running cyclic LLM agent workflows — loops, conditional routing, parallel fan-out, and nested subgraphs. See flattop.io for full docs.
- Quick Start — your first workflow in 5 minutes
- Core Concepts — graphs, nodes, agents, state
- Patterns — runnable guides for each built-in pattern
- Troubleshooting — common errors, fixes, and the gotchas that fail silently
- Examples - runnable examples for each built-in pattern and infrastructure setup
See the Quick Start guide for a complete walkthrough.
npm install @cycgraph/orchestratorOptional packages
- @cycgraph/memory - Temporal knowledge graph + xMemory-inspired hierarchical retrieval (messages → episodes → facts → themes).
- @cycgraph/context-engine - Optional prompt compression pipeline — strips redundant facts, verbose serialisation, and stale reasoning traces from memory payloads.
- @cycgraph/orchestrator-postgres - Postgres + pgvector adapter for durable state, event log, agent registry, and memory store.
- @cycgraph/evals - Regression-test harness for agent workflows with deterministic + LLM-as-judge assertions.
Each pattern is a node type. Declarative, composable, and traced through OpenTelemetry.
- Reflection Distill run output into atomic facts that future runs retrieve
- Evolution (DGM) Generate N candidates per generation, score fitness, breed the winners
- Supervisor An LLM decides which specialist worker should run next, iteratively
- Swarm Peer agents hand off work to each other based on competence
- Map-Reduce Fan out an array of items to parallel workers, then merge
- Self-Annealing Iteratively refine a single output, dropping temperature each pass
- Human-in-the-Loop Pause for a human reviewer; resume hours later from the exact checkpoint
- Verifier LLM-judge / filtrex expression / JSONPath assertion
- Voting consensus across N voter agents
- Subgraph nested workflows with isolated state
- Proof the learning loop works (with charts)
- A research agent that learns over runs
- Multi-specialist routing
- Quality loop until score ≥ N
- Parallel research workers + merge
- Verify-and-fix with deterministic gates
- Voting / consensus across N agents
- Evolutionary candidate breeding
- Pause for human review + resume
- MCP tools (web search, fetch)
- Local Ollama models
- Postgres durable execution
Node and graph configuration for running agents with guardrails.
- Per-node budgets — set limits per node on cost, tokens, or tool calls. A runaway agent can't drain the workflow.
- Zero-trust state slicing — every node sees only what it declares. The engine rejects undeclared writes.
- Taint tracking — every string from an external MCP tool is flagged in an append-only registry and propagates through derived values; strict mode rejects tainted data in routing conditions.
- Fact sanitization — hook screens every reflection fact before it persists (PII redaction, policy filtering); fails closed by default.
- Eval-gated retention — lessons enter on trial and are kept only if runs that used them verifiably scored better; harmful ones are evicted on outcome evidence alone.
- Human-in-the-loop gates — pause for approval and resume hours later from the exact checkpoint, surviving process restarts.
- MCP server registry — stdio transports restricted to an allowlist, http/sse URLs SSRF-guarded, schemas re-validated on every read/write.
Issues and PRs welcome. See CONTRIBUTING.md for development setup, coding standards, and the architecture decisions worth knowing before opening a PR. Security disclosures go through SECURITY.md.