crinzo-plugins

helix

A self-learning orchestrator for Claude Code. Memory that earns its place through demonstrated usefulness.

The Core Insight

Most agent memory systems accumulate knowledge indefinitely—storing everything, hoping relevance will emerge. The important signals can easily drown as storage noise grows.

Helix inverts this: memories must prove their worth. Every insight tracks an effectiveness score (0-1) that updates via weighted EMA based on causal similarity strength. Insights that consistently help rise in ranking; ineffective ones decay toward neutral and eventually prune. The system learns what actually works, not what seemed important at storage time.

Insight injected → Builder executes → Outcome reported → Weighted feedback (similarity-proportional)
       ↑                                                         ↓
       └─────────── Future recalls rank by proven effectiveness ─┘
                          ↕ graph neighbors
                    ↕ velocity boost for active insights
              ↕ cross-session pattern synthesis

This closes the learning loop. Insights also form a graph—auto-linked by semantic similarity at storage, connected by provenance (led_to) when one insight spawns another. Recall can traverse these edges, surfacing related knowledge that keyword and vector search alone would miss.

Why Now

Opus 4.6 broke the pattern. Previous agent harnesses focused on constraining LLM tendencies—scope creep, over-engineering, context drift. They added guardrails, checkpoints, and hand-holding to compensate for model limitations.

Opus 4.6 doesn't need training wheels. It reasons well, follows instructions, and stays on task. Helix builds on this capability jump: prose-driven orchestration, minimal scaffolding, maximum model autonomy. The orchestrator is a markdown file (SKILL.md), not a state machine.

How It Works

/helix <objective>
       │
       ▼
┌──────────────────────────────────────┐
│  RECALL (graph_hops=1)               │
│  Query memory for strategic insights │
│  Graph-expand via similar/led_to     │
│  → CONSTRAINTS + exploration targets │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  EXPLORE (parallel, sonnet)          │
│  Swarm maps codebase structure       │
│  Scope informed by recalled insights │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  PLAN (opus)                         │
│  Decomposes into task DAG            │
│  Respects CONSTRAINTS from memory    │
│  Tactical insights via hook          │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  BUILD (parallel, opus)              │
│  Execute tasks with insight context  │
│  Auto-feedback on task outcome       │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  LEARN                               │
│  Observe patterns + check provenance │
│  Ask user for domain knowledge       │
│  Store validated insights            │
└──────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│  COMPLETE                            │
│  Verify learning loop closed         │
│  Report session summary              │
└──────────────────────────────────────┘

Three specialized agents, each receiving context tuned to their role:

• Explorers map codebase structure via a 5-step procedure (orient → map interfaces → trace dependencies → sample implementations → locate tests), receiving recalled insight context to prioritize areas the system has learned matter.
• Planners decompose objectives into task DAGs with explicit task-sizing rules, dependency validation (data dependencies only—conceptual relatedness is not a dependency), concrete verification commands per task type, and anti-pattern guardrails.
• Builders execute tasks through structured phases (pre-flight → implement → verify → failure diagnosis) with categorized error handling and two-attempt retry logic.

Learning extraction and feedback attribution happen automatically via hooks.

Memory flows at two levels: the RECALL phase gives the orchestrator strategic context—decomposition constraints, risk areas, sequencing hints—which it synthesizes into a CONSTRAINTS block for the planner and exploration targets for the explorer swarm. Separately, the SubagentStart hook injects tactical insights directly into builder and planner prompts. Both use graph_hops=1 (the default), expanding results through similar and led_to edges to surface related insights beyond direct vector/keyword matches. Strategic and tactical memory are complementary; neither duplicates the other.