CYCGRAPH

Build and compose your own agent workflows with a unified engine for running custom workflows with helpful built-in patterns like supervisor, swarm, map-reduce, and reflection.

• Quick Start - build 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

Install

See the Quick Start guide for a complete walkthrough.

npm install @cycgraph/orchestrator

Optional 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/tools - MCP and tools library.
• @cycgraph/evals - Regression-test harness for agent workflows with deterministic + LLM-as-judge assertions.

Quickstart

import { agent, node, graph, run } from '@cycgraph/orchestrator';

const research = node({
  id: 'research',
  agent: agent({
    model: 'claude-sonnet-4-6',
    instructions: 'You are a research specialist. Produce concise, factual notes.',
  }),
  writes: 'notes',
});

const write = node({
  id: 'write',
  agent: agent({
    model: 'claude-sonnet-4-6',
    instructions: 'Turn the research notes into a clear summary under 300 words.',
  }),
  reads: [research.writes],
  writes: 'draft',
});

const workflow = graph({
  name: 'research-write',
  nodes: [research, write],
  edges: [{ from: research, to: write }],
});

run(workflow, { goal: 'Explain how LLMs work' });

Studio

The studio is a dashboard over everything the engine records. Browse runs and their live log streams, inspect a workflow's topology, and let the improve lo op measure a workflow against its own evals. When a measured change wins, the studio walks it from proposal to a committed branch. Pushing stays yours.

See @cycgraph/studio for setup.

Built-in Patterns

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 Compose whole graphs as reusable blocks with isolated state

Examples

• 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

Safety

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.

Contributing

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.

License

Apache 2.0.