convez.ai
MCP ServerAutomaçãoAvançado
wmcmahan

cycgraph – Motor de Orquestração com Aprendizado Cumulativo

wmcmahan/cycgraph

Workflows que aprendem e melhoram a cada ciclo, com segurança produtiva

Ver no GitHub
BomPluginScore · de 0 a 100

Engine TypeScript para orquestração de agentes que melhoram automaticamente a cada execução através de loops de reflexão, armazenamento durável de lições e guardrails de produção (budgets por nó, rastreamento de contaminação, HITL). Implementa 12 tipos de nós incluindo Supervisor, Evolution e Reflection, nativo para MCP.

Instalação

$npx convez-ai wmcmahan/cycgraph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 2 semanas
Versão
@cycgraph/context-engine@0.7.8
Issues abertas
0
Contribuidores
2

Casos de uso

  • Orquestração de agentes multi-nó com memória durável entre execuções
  • Pesquisa iterativa e análise que se refinam automaticamente a cada run
  • Sistemas críticos que precisam de eval-gates e rastreamento de taint

Veredito

Ferramenta sólida (v0.2.0) para quem precisa orquestração sofisticada com learning loop mensurado e guardrails reais. O benchmark de aprendizado composto (0.00→1.00 em 5 runs) é genuíno; cuidado: complexidade bem acima da média e requer TypeScript/Node 24+.

README

A tradução para o português deste README ainda está na fila.

cycgraph

Agent workflows that get smarter every run.

npm CI License: Apache 2.0 Node.js Docs

📚 Documentation  ·  📈 Compound Learning Benchmark  ·  🧪 Examples  ·  🐛 Issues


cycgraph is a TypeScript orchestration engine where workflows learn from their own runs. A reflection node distills each run's output into atomic lessons; a memory store persists them; and every future run retrieves them automatically into its prompts. The loop is measurable, reproducible, and guarded by production-safety primitives — per-node budgets, taint tracking, and human-in-the-loop gates — so letting a workflow improve itself doesn't mean letting it off the leash.

And it's measured, not just animated — same model, same five topics, same order:

The solid line above is a research → critique → reflect workflow whose researcher retrieves accumulated lessons before every run; the dashed line is the identical researcher with the loop disabled. Fitness is scored outside the workflow — half deterministic rubric checks, half a multi-sample LLM judge — and the agents never see the rubric or their scores. In our first recorded run the learning workflow went 0.00 → 1.00 in five runs while the control averaged 0.18. Reproduce it for under $1: packages/evals/examples/compound-learning-benchmark.

Status: 0.2.0 — first stable release. Semver applies (0.x rules: breaking changes only arrive with a minor bump). Core primitives (graph engine, durable execution, memory, eval-gated learning, MCP integration) are covered by 2,400+ tests and exercised by the runnable examples.

How the learning loop works

import { GraphRunner, createGraph, createWorkflowState } from '@cycgraph/orchestrator';

const graph = createGraph({
  name: 'Learning Research Agent',
  description: 'Researches a topic, reflects on lessons, compounds across runs',
  nodes: [
    {
      id: 'research',
      type: 'agent',
      agent_id: RESEARCHER,
      read_keys: ['goal'],
      write_keys: ['notes'],
      memory_query: { tags: ['lesson:research-v1'], max_facts: 20 },  // ← lessons in
      budget: { max_cost_usd: 0.10 },                                  // ← hard cost cap
    },
    {
      id: 'reflect',
      type: 'reflection',                                              // ← lessons out
      read_keys: ['notes'],
      write_keys: ['reflect_reflection'],
      reflection_config: {
        source_keys: ['notes'],
        extractor: { type: 'rule_based', min_sentence_length: 25 },
        tags: ['lesson', 'lesson:research-v1'],
      },
    },
  ],
  edges: [{ source: 'research', target: 'reflect' }],
  start_node: 'research',
  end_nodes: ['reflect'],
});

const runner = (goal: string) => new GraphRunner(
  graph,
  createWorkflowState({ workflow_id: graph.id, goal }),
  { memoryWriter, memoryRetriever },
);

await runner('Evaluating scientific source credibility').run();
await runner('Evaluating news source credibility').run();  // run 2 knows what run 1 learned

The reflection node distills run output into tagged facts via your memoryWriter; any node carrying a memory_query gets matching facts rendered into a ## Relevant Memory section of its prompt before execution — zero manual injection. Full runnable version with the memory adapters: examples/learning-research-agent.

Guardrails that make self-improvement shippable

A workflow that changes its own behavior needs harder rails than one that doesn't. These are first-class, not middleware:

  • Per-node budgets — budget: { max_tokens, max_cost_usd } on every node. A runaway agent can't drain the workflow.
  • Zero-trust state slicing — read_keys / write_keys default to []; 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 — a factSanitizer hook screens every reflection fact before it persists (PII redaction, policy filtering); fails closed by default.
  • Eval-gated retention (verified lessons) — lessons enter on trial and are kept only if runs that used them verifiably scored better; harmful ones are evicted on outcome evidence alone. In the adversarial demo, three deliberately poisoned lessons cratered a run and the gate evicted all three two runs later — no human touched the store.
  • 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.

What makes cycgraph different

cycgraphMost agent frameworks
Compound learning across runsFirst-class reflection node + MemoryWriter + tag-scoped retrieval, with a reproducible benchmark. Agents that ran yesterday inform agents that run today.Usually a separate vector-store integration you wire yourself
Per-node resource budgetsbudget: { max_tokens, max_cost_usd } on every nodeTypically workflow-wide caps
Zero-trust state slicingEvery node declares read_keys / write_keys. Taint tracking on external data, MCP server allowlists, prompt-injection guards.Often middleware or hand-wired
Cyclic by designLoops, conditional routing, and nested subgraphs are native operations — not a DAG with backward-pointing edges bolted on.DAG-shaped with workarounds
TypeScript-firstZod schemas at every boundary, strict mode throughout, MCP-native tool integration.Mostly Python ecosystems with TS as a port
Durable executionEvent-sourced replay, atomic state snapshots, saga compensation, HITL pauses that survive process restarts.Varies by framework

Built-in patterns

Each pattern is a node type. Declarative, composable, and traced through OpenTelemetry.

PatternUse it when
ReflectionDistill run output into atomic facts that future runs retrieve
Evolution (DGM)Generate N candidates per generation, score fitness, breed the winners
SupervisorAn LLM decides which specialist worker should run next, iteratively
SwarmPeer agents hand off work to each other based on competence
Map-ReduceFan out an array of items to parallel workers, then merge
Self-AnnealingIteratively refine a single output, dropping temperature each pass
Human-in-the-LoopPause for a human reviewer; resume hours later from the exact checkpoint

Plus deterministic primitives: verifier (LLM-judge / filtrex expression / JSONPath assertion), voting (consensus across N voter agents), subgraph (nested workflows with isolated state).

What you get

  • Compound learning across runs — reflection node distills run output into atomic facts; future runs retrieve them via memory_query on any agent node. Backed by a temporal knowledge graph in @cycgraph/memory.
  • Production-safety primitives — per-node budget, factSanitizer for PII redaction, taint tracking, zero-trust read_keys/write_keys, prompt-injection guards.
  • Cyclic graph engine — loops, retries, conditional routing via filtrex, nested subgraphs, parallel fan-out/fan-in. 12 node types — see the Nodes reference.
  • Durable execution — event-sourced replay, atomic state snapshots, saga compensation, auto-compaction.
  • Streaming — stream() async generator with real-time token deltas, tool-call events, and typed lifecycle events.
  • MCP tools — built-in default servers (web search, fetch), tool manifest caching, per-tool circuit breakers.
  • Observability — 17 lifecycle events, OpenTelemetry spans, Prometheus metrics, per-agent + per-workflow token/cost tracking.
  • Distributed execution — WorkflowWorker + durable job queue for multi-process deployments, with crash recovery and run fencing (a reclaimed worker can't clobber the new owner).

Quick start

In your project:

npm install @cycgraph/orchestrator

Try a runnable example first (no project needed):

git clone https://github.com/wmcmahan/cycgraph.git && cd cycgraph && npm install
ANTHROPIC_API_KEY=sk-ant-... npx tsx packages/orchestrator/examples/research-and-write/research-and-write.ts

See the Quick Start guide for a complete walkthrough. The examples/ directory has runnable scripts for every built-in pattern plus infrastructure setups (Postgres, Ollama, MCP) — the table below points at the most commonly searched-for ones.

Examples by what you're trying to build

Packages

PackageWhat it does
@cycgraph/orchestratorCore graph engine. Zero infrastructure dependencies.
@cycgraph/memoryTemporal knowledge graph + xMemory-inspired hierarchical retrieval (messages → episodes → facts → themes).
@cycgraph/context-engineOptional prompt compression pipeline — strips redundant facts, verbose serialisation, and stale reasoning traces from memory payloads.
@cycgraph/orchestrator-postgresPostgres + pgvector adapter for durable state, event log, agent registry, and memory store.
@cycgraph/evalsRegression-test harness for agent workflows with deterministic + LLM-as-judge assertions.

Documentation

The full documentation site lives at flattop.io:

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.

Ver o original no GitHub

Bom para

Relacionados