CYCGRAPH is built on the core idea that agent workflows should be easily composable to solve complex problems, portable across runtimes, connectable to each other across systems, and allow full observability and ownership.
- 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
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/tools - MCP and tools library.
- @cycgraph/evals - Regression-test harness for agent workflows with deterministic + LLM-as-judge assertions.
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' });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.
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
- 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.
