Helix

Self-healing runtime for autonomous agents. Fix once, immune forever.

Agent payment intelligence — predict costs, optimize execution, fix failures. Powered by VialOS Runtime.

Your agent's API call failed. Helix diagnosed it, fixed it, and remembered. Next time — instant fix, zero cost. Think of stackoverflow + crowdstrike for agents.

// Before: hope for the best
await agent.sendPayment(invoice);

// After: self-healing in one line
const safePay = wrap(agent.sendPayment.bind(agent), { mode: 'auto' });
await safePay(invoice);

---

If this helped, please ⭐ — it helps us reach more developers.

How It Works

Helix wraps your function. When it fails, a 6-stage pipeline kicks in:

Error occurs → Perceive → Construct → Evaluate → Commit → Verify → Gene
                  │           │           │          │         │       │
            What broke?   Find fixes   Score them  Execute  Worked?  Remember

The fix is stored in the Gene Map — a SQLite knowledge base scored by reinforcement learning. Next time the same error hits any agent, it's fixed in under 1ms. No diagnosis, no LLM call, no cost.

Benchmarks

• 1,083 Base Mainnet transactions (12hr A/B test) — Helix: 99.9% vs blind retry: 81.9%
• 5 frontier LLMs (GPT-4o-mini, GPT-4o, Claude Opus 4.6, GPT-5.4-mini, GPT-5.4) tested on bare execution reverted — all failed. PCEC: 100%.
• Gene Map warm: 2,140ms → 1.1ms, $0.49 → $0.00 per repair
• Full eval harness: experiments/

Quick Start

npm install @helix-agent/core

import { wrap } from '@helix-agent/core';

// Wrap any async function — payments, API calls, anything
const safeCall = wrap(myFunction, { mode: 'auto' });
const result = await safeCall(args);

// Errors are automatically:
//   1. Diagnosed (what type of error?)
//   2. Fixed (modify params, retry with backoff, refresh token...)
//   3. Remembered (next time → instant fix)

Demo

Three modes, three risk levels:

Mode	Behavior	Risk
observe	Diagnose only, never touch your call	Zero
auto	Diagnose + fix params + retry	Low — only changes how, never what
full	Auto + fund movement strategies	Medium

Powered by VialOS Runtime

Helix is the first vertical product of VialOS — an AI agent operating system. The VialOS Runtime provides the PCEC engine, Gene Map, and all learning modules. Helix adds payment-specific adapters on top.

@vial/core              Generic self-healing engine
  ├── PCEC Engine        6-stage repair pipeline
  ├── Gene Map           SQLite knowledge base + RL scoring
  ├── Self-Refine        Iterative failure refinement
  ├── Meta-Learning      3 similar fixes → pattern → 4th is instant
  ├── Safety Verifier    7 pre-execution constraints
  ├── Self-Play          Autonomous error discovery
  ├── Federated Learning Privacy-preserving distributed RL
  └── Prompt Optimizer   LLM classification auto-improves

@helix-agent/core        Payment vertical (powered by Vial)
  ├── Coinbase           17 error patterns (CDP, ERC-4337, x402)
  ├── Tempo              13 error patterns (MPP, session, DEX)
  ├── Privy              7 error patterns (embedded wallet)
  └── Generic            3 error patterns (HTTP)

@vial/adapter-api        API vertical (powered by Vial)
  ├── Rate limits        429, throttle
  ├── Server errors      500, 502, 503, 504
  ├── Timeouts           ETIMEDOUT, socket, gateway
  ├── Connection         ECONNREFUSED, ECONNRESET, DNS
  ├── Auth               401, 403, expired token
  └── Client             400, 413, 422, parse errors

Build your own adapter — implement the PlatformAdapter interface for any domain:

import { wrap } from '@vial/core';
import type { PlatformAdapter } from '@vial/core';

const myAdapter: PlatformAdapter = {
  name: 'my-service',
  perceive(error) {
    if (error.message.includes('rate limit'))
      return { code: 'rate-limited', category: 'throttle', strategy: 'backoff_retry' };
    return null;
  },
  getPatterns() { return [/* ... */]; },
};

const safeCall = wrap(myFunction, { adapter: myAdapter, mode: 'auto' });

VialOS Beta Features

Helix runs on the VialOS Runtime. Enable VialOS integration with --beta:

npx @helix-agent/core serve --port 7842 --mode observe --beta

This activates:

• GET /vial/status — VialOS runtime information (13 modules, 5 adapters)
• VialOS metadata in GET /health response
• "Powered by VialOS Runtime" dashboard badge

Without --beta, Helix behaves identically to the stable release.

What Makes This Different

	Sentry/Datadog	Simple retry	Helix
Detects errors	✅	❌	✅
Fixes errors	❌	⚠️ blind retry	✅ smart fix
Learns from fixes	❌	❌	✅ Gene Map
Cross-agent learning	❌	❌	✅ Federated
Safety constraints	N/A	❌	✅ 7 checks

Sentry tells you something broke. Helix fixes it.

Installation

TypeScript/JavaScript:

npm install @helix-agent/core

Python:

pip install helix-agent-sdk

Docker:

docker run -d -p 7842:7842 adrianhihi/helix-server

REST API:

curl -X POST http://localhost:7842/repair \
  -H 'Content-Type: application/json' \
  -d '{"error": "nonce too low", "platform": "coinbase"}'

CLI

# ⚠️ Use @helix-agent/core — "npx helix" installs a WRONG third-party package
npx @helix-agent/core serve --port 7842          # Start server + dashboard
npx @helix-agent/core scan ./src                 # Scan codebase for error patterns
npx @helix-agent/core simulate "nonce too low"   # Dry-run diagnosis
npx @helix-agent/core self-play 10               # Autonomous error discovery
npx @helix-agent/core dream                      # Memory consolidation
npx @helix-agent/core discover                   # Find adapter gaps

Architecture

Helix includes 15 learning and safety modules, all integrated into the core PCEC pipeline:

Learning — Gene Map (RL), Meta-Learning (few-shot), Causal Graph (prediction), Negative Knowledge (anti-patterns), Adaptive Weights (auto-tuning), Self-Play (exploration), Federated Learning (distributed), Gene Dream (memory consolidation), Prompt Optimizer (LLM self-improvement), Auto Strategy Generation (creates new fixes via LLM)

Safety — 7 pre-execution constraints (never modifies recipient or calldata), 4-layer adversarial defense (reputation, verification, anomaly detection, auto-rollback), cost ceilings, strategy allowlists

Execution — refresh_nonce, speed_up (gas × 1.3), reduce_request (value ÷ 2), backoff_retry (1s → 2s → 4s → 8s → 16s cap), renew_session (callback), split_transaction, remove_and_resubmit

Self-Evolution

Helix doesn't just fix errors — it gets better over time:

Level 1: Data Evolution
  Every fix improves Q-values → better strategy selection

Level 2: Strategy Evolution  
  Meta-Learning spots patterns across fixes
  Self-Play discovers errors before users hit them
  Gene Dream consolidates knowledge during idle time

Level 3: Architecture Evolution
  Auto Strategy Generation invents new fix methods via LLM
  Adaptive Weights auto-tunes scoring per error category
  Auto Adapter Discovery detects when new platforms need support

Stats

553+ tests across 59 files
Schema v12 (auto-migrating)
61 error patterns (40 payment + 21 API)
21 API error patterns
7 safety constraints
12 repair strategies

Roadmap

✅ Phase 1 — Local procedural memory

• PCEC Engine — 6-stage self-healing pipeline
• Gene Map — SQLite + Q-value reinforcement learning
• Platform Adapters — Coinbase, Tempo, Privy, Generic HTTP
• Self-Evolution — Meta-Learning, Self-Play, Gene Dream
• Safety — 7 constraints, adversarial defense, cost ceilings
• CI/CD Integration — npx @helix-agent/core scan for GitHub Actions
• Vial Framework — Generic core extracted (@vial/core)
• API Adapter — Second vertical proving generic architecture
• Self-Refine — Iterative failure reflection (paper: Self-Refine)
• Prompt Optimizer — LLM classification auto-improves (paper: DSPy)
• VialOS Beta — --beta flag for VialOS Runtime integration
• agentfolded — One-command Vial skill deployment across Claude Code, Cursor, Codex CLI (published to ClawHub as vial-self-healing v0.6.3)
• n8n Community Node — n8n-nodes-vialos, MIT, npm v0.1.0, 8 error patterns

🔄 Phase 2 — Cross-domain validation

• Web2 microservices — 91% autonomous resolution across 4 production-scale services, zero LLM calls
• On-chain agents — 99.9% vs 81.9% blind retry, 1,083 Base Mainnet transactions
• @vial-agent/gene-map — Standalone package: same Gene Map substrate, any execution shape

📅 Phase 3 — Team-level procedural memory

• Gene Registry Cloud — Shared execution knowledge across agents and teams
• Budget Predictor — Predict task cost from Gene Map history before execution
• CI/CD adapter — Third vertical: deploy failures, flaky tests

🔭 Phase 4 — Emergent knowledge

• Auto-generated runbooks — Operational patterns that emerge from execution data
• Proactive suggestions — Anticipate failures before they happen
• arXiv paper — "Vial: Procedural Memory Infrastructure for Production AI Agents"

Research

Helix implements ideas from these papers:

Paper	What We Took	Module
Reflexion	Verbal reinforcement from failures	Negative Knowledge
ExpeL	Experience-conditioned strategy selection	Conditional Genes
Voyager	Skill library that grows over time	Auto Strategy Gen
Self-Refine	Iterative refinement with self-feedback	Self-Refine loop
DSPy	Self-improving LLM pipelines	Prompt Optimizer
Mem0	Scalable long-term memory	Gene Dream

Contributing

Contributions welcome. The easiest way to contribute is to write a new PlatformAdapter for a domain you care about.

git clone https://github.com/adrianhihi/helix
cd helix
npm install
npm run build
npm run test   # 553+ tests should pass

See CONTRIBUTING.md for guidelines.

Star History

FAQ

What is Helix?

Helix is a self-healing runtime for autonomous agents — fix once, immune forever. It provides agent payment intelligence: predict costs, optimize execution, fix failures. Powered by VialOS Runtime.

How does the 6-stage pipeline work?

Stage	Action	Description
Perceive	What broke?	Error diagnosis
Construct	Find fixes	Generate solutions
Evaluate	Score them	Rank solutions
Commit	Execute	Apply fix
Verify	Worked?	Validate success
Gene	Remember	Store in Gene Map

What is the Gene Map?

A SQLite knowledge base scored by reinforcement learning. When the same error hits again, it's fixed in under 1ms — no diagnosis, no LLM call, no cost.

How do I use Helix?

import { wrap } from '@helix-agent/core';

const safeCall = wrap(myFunction, { mode: 'auto' });
const result = await safeCall(args);

What are the benchmarks?

Benchmark	Result
1,083 Base Mainnet transactions (12hr A/B test)	Helix: 99.9% vs blind retry: 81.9%
5 frontier LLMs on execution reverted	All failed, PCEC: 100%
Gene Map warm repair	2,140ms → 1.1ms, $0.49 → $0.00

How do I install?

npm install @helix-agent/core
# or
pip install helix-agent-sdk

Where can I find more info?

• npm: @helix-agent/core
• PyPI: helix-agent-sdk
• Docker: adrianhihi/helix-server

What license applies?

MIT License.

License

MIT

Links

• npm: @helix-agent/core
• PyPI: helix-agent-sdk
• Docker: adrianhihi/helix-server
• awesome-mpp — Listed in the MPP ecosystem registry