Skip to main content

​
What is a Gene?

A Gene is a reusable strategy for handling specific problem patterns in agent evolution. Genes define:
  • Signal Patterns they respond to (signals_match)
  • Category of change (repair, optimize, innovate)
  • Strategy steps to follow
  • Constraints on blast radius
  • Validation commands that must pass

​
Gene Structure

​
type
string
required
Must be "Gene"
​
id
string
required
Unique identifier (e.g., gene_gep_repair_from_errors)
​
category
string
required
One of: repair, optimize, innovate
​
signals_match
array
required
Array of signal keywords this Gene handles
​
preconditions
array
Human-readable conditions for when this Gene applies
​
strategy
array
required
Step-by-step strategy for applying this Gene
​
constraints
object
required
Blast radius limits and forbidden paths
​
validation
array
required
Commands that must pass before solidifying changes

​
Real Gene Examples

​
Repair Gene: gene_gep_repair_from_errors

This Gene handles error-related signals by applying minimal, reversible patches. 
{
  "type": "Gene",
  "id": "gene_gep_repair_from_errors",
  "category": "repair",
  "signals_match": [
    "error",
    "exception",
    "failed",
    "unstable"
  ],
  "preconditions": [
    "signals contains error-related indicators"
  ],
  "strategy": [
    "Extract structured signals from logs and user instructions",
    "Select an existing Gene by signals match (no improvisation)",
    "Estimate blast radius (files, lines) before editing",
    "Apply smallest reversible patch",
    "Validate using declared validation steps; rollback on failure",
    "Solidify knowledge: append EvolutionEvent, update Gene/Capsule store"
  ],
  "constraints": {
    "max_files": 20,
    "forbidden_paths": [".git", "node_modules"]
  },
  "validation": [
    "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify",
    "node scripts/validate-modules.js ./src/gep/selector ./src/gep/memoryGraph"
  ]
}
Signal Patterns:
  • Log lines containing “error”, “exception”, “failed”
  • Stack traces or error messages in memory
  • User instructions mentioning “fix” or “repair”
Example Trigger:
signals: ["log_error", "errsig:**TOOLRESULT**: {...}", "windows_shell_incompatible"]
Selector Output:
{
  "selected": "gene_gep_repair_from_errors",
  "reason": [
    "signals match gene.signals_match",
    "signals: log_error, exception, failed"
  ]
}

​
Optimize Gene: gene_gep_optimize_prompt_and_assets

This Gene handles protocol improvements and prompt refinements. 
{
  "type": "Gene",
  "id": "gene_gep_optimize_prompt_and_assets",
  "category": "optimize",
  "signals_match": [
    "protocol",
    "gep",
    "prompt",
    "audit",
    "reusable"
  ],
  "preconditions": [
    "need stricter, auditable evolution protocol outputs"
  ],
  "strategy": [
    "Extract signals and determine selection rationale via Selector JSON",
    "Prefer reusing existing Gene/Capsule; only create if no match exists",
    "Refactor prompt assembly to embed assets (genes, capsules, parent event)",
    "Reduce noise and ambiguity; enforce strict output schema",
    "Validate by running node index.js run and ensuring no runtime errors",
    "Solidify: record EvolutionEvent, update Gene definitions, create Capsule on success"
  ],
  "constraints": {
    "max_files": 20,
    "forbidden_paths": [".git", "node_modules"]
  },
  "validation": [
    "node scripts/validate-modules.js ./src/evolve ./src/gep/prompt"
  ]
}
Signal Patterns:
  • Keywords: “protocol”, “gep”, “audit”, “reusable”
  • User requests for better prompt structure
  • Need for stricter output validation
Example Strategy Application:
  1. Detect ambiguous prompt sections
  2. Refactor to embed Gene/Capsule assets directly
  3. Add schema validation for outputs
  4. Run validation commands
  5. Create Capsule on success

​
Innovate Gene: gene_gep_innovate_from_opportunity

This Gene handles feature requests and capability gaps when the system is stable. 
{
  "type": "Gene",
  "id": "gene_gep_innovate_from_opportunity",
  "category": "innovate",
  "signals_match": [
    "user_feature_request",
    "user_improvement_suggestion",
    "perf_bottleneck",
    "capability_gap",
    "stable_success_plateau",
    "external_opportunity"
  ],
  "preconditions": [
    "at least one opportunity signal is present",
    "no active log_error signals (stability first)"
  ],
  "strategy": [
    "Extract opportunity signals and identify the specific user need or system gap",
    "Search existing Genes and Capsules for partial matches (avoid reinventing)",
    "Design a minimal, testable implementation plan (prefer small increments)",
    "Estimate blast radius; innovate changes may touch more files but must stay within constraints",
    "Implement the change with clear validation criteria",
    "Validate using declared validation steps; rollback on failure",
    "Solidify: record EvolutionEvent with intent=innovate, create new Gene if pattern is novel, create Capsule on success"
  ],
  "constraints": {
    "max_files": 25,
    "forbidden_paths": [".git", "node_modules"]
  },
  "validation": [
    "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify"
  ]
}
Signal Patterns:
  • User feature requests
  • Performance bottlenecks
  • Capability gaps identified
  • System stable with no errors (precondition)
Stability-First Rule: This Gene does not activate if log_error signals are present. Repair takes priority.Blast Radius: Innovate changes are allowed up to 25 files (vs. 20 for repair/optimize).

​
Signal Matching

​
How Signals Match Genes

The selector computes overlap between input signals and signals_match arrays: 
// Example from src/gep/selector.js
function scoreGene(gene, signals) {
  const matches = gene.signals_match.filter(pattern => 
    signals.some(sig => sig.includes(pattern))
  );
  return matches.length / gene.signals_match.length;
}

​
Signal Extraction

Signals are extracted from multiple sources:
1

Error Logs

Parse log_error, stack traces, error messages
2

User Instructions

Extract keywords from natural language (e.g., “fix”, “add”, “optimize”)
3

Memory Graph

Use historical signal patterns that led to success
4

Environment

Platform-specific signals (e.g., windows_shell_incompatible)

​
Validation Commands

​
Command Structure

All validation commands use repo-root-relative paths: 
// From src/gep/assetStore.js
function buildValidationCmd(relModules) {
  const paths = relModules.map(m => `./${m}`);
  return `node scripts/validate-modules.js ${paths.join(' ')}`;
}

​
Safety Checks

Before executing, all commands are validated (src/gep/solidify.js): 
function isValidationCommandAllowed(cmd) {
  // 1. Must start with node/npm/npx
  if (!cmd.match(/^(node|npm|npx)\s/)) return false;
  
  // 2. No command substitution
  if (cmd.includes('`') || cmd.includes('$(')) return false;
  
  // 3. No shell operators (after stripping quoted strings)
  const stripped = cmd.replace(/(["'])(?:(?=(\\?))\2.)*?\1/g, '');
  if (stripped.match(/[;&|><]/)) return false;
  
  return true;
}

​
Example Validation Report

{
  "type": "ValidationReport",
  "id": "vr_1770477654235",
  "gene_id": "gene_gep_repair_from_errors",
  "commands": [
    {
      "command": "node scripts/validate-modules.js ./src/evolve ./src/gep/solidify",
      "ok": true,
      "stdout": "ok\n",
      "stderr": ""
    },
    {
      "command": "node scripts/validate-modules.js ./src/gep/selector ./src/gep/memoryGraph",
      "ok": true,
      "stdout": "ok\n",
      "stderr": ""
    }
  ],
  "overall_ok": true,
  "duration_ms": 80
}

​
Gene Categories

​
Repair

Purpose: Fix errors and restore stability Characteristics:
  • Smallest blast radius (max 20 files)
  • Highest priority when errors present
  • Validation must include affected modules
  • Reversible patches only

​
Optimize

Purpose: Improve existing functionality Characteristics:
  • Medium blast radius (max 20 files)
  • Focus on code quality, performance, protocol
  • Requires clear “before/after” validation

​
Innovate

Purpose: Add new features and capabilities Characteristics:
  • Largest blast radius (max 25 files)
  • Only activates when stable (no errors)
  • May create new Genes for novel patterns
  • Higher risk tolerance

​
Creating Custom Genes

1

Identify Pattern

Find a recurring problem or opportunity in your agent’s evolution history
2

Define Signals

List keywords that should trigger this Gene
3

Write Strategy

Break down the solution into clear, actionable steps
4

Set Constraints

Define max files, forbidden paths, timeout limits
5

Declare Validation

List all commands that must pass before solidifying
6

Test in Isolation

Manually trigger the Gene and verify it behaves correctly

​
Gene Selection Priority

When multiple Genes match the same signals:
  1. Memory Preference: Genes with successful history get boosted
  2. Signal Overlap: Higher match percentage wins
  3. Category Priority: Repair > Optimize > Innovate
  4. Explicit User Intent: User instructions can override

​
Next Steps

Capsules

See how successful Gene applications become reusable Capsules

Events

Track evolution history through EvolutionEvent trees

Build docs developers (and LLMs) love

Get started for freeTalk to us