How-To Guide

AI Genome Lab Guide

Step-by-step guide to evolving behavioral DNA for your AI agents

Check Your Current Genome State

See where your genome is before you start evolving it

Every ACE account starts with a default master genome — 8 traits at baseline expression levels. Check your starting point.

# MCP — quick fingerprint
ace_genome_state({ agent_name: "master" })

# MCP — full serialization
ace_genome_state({ agent_name: "master", full_serialize: true })

# REST API
curl http://localhost:7777/api/v1/{namespace}/genome/master/state \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

What you'll see:

PRC Perception

RSN Reasoning

EMP Empathy

MEM Memory

EXP Expression

ADP Adaptation

REG Regulation

INT Integration

Each trait ranges 0.0–2.0. A fresh genome starts around 1.0 for all traits.

Express Text Through Your Genome

The core evolution loop — each expression makes the genome adapt

The ace_genome_express tool is the primary way to train your genome. It runs the full pipeline: ground the text, express through 8 genes, evolve traits, and produce behavioral guidance.

# Express a debugging session through the genome
ace_genome_express({
  text: "Found a race condition in the auth middleware. The session
token was being validated after the request handler started, causing
intermittent 401 errors under high load. Fixed by moving validation
to a pre-handler hook.",
  agent_name: "master"
})

# Express architecture work
ace_genome_express({
  text: "Decided to use event sourcing for the audit trail. This gives
us full replay capability and time-travel debugging. Trade-off: higher
storage cost and more complex querying.",
  agent_name: "master"
})

How it works: The text is analyzed for 16 facets (8 emotional + 8 logical). Debugging text activates RSN and PRC. Architecture text activates INT and REG. The genome's expression levels shift proportionally.

Ground Text (Optional Deep Dive)

See exactly how text is analyzed before it hits the genome

Use ace_genome_ground to see the raw grounding analysis without evolving the genome. Useful for understanding what type of text trains which traits.

# Ground without evolving
ace_genome_ground({
  text: "The deployment pipeline is fragile. We need circuit breakers
and retry logic before the next release."
})

# Returns: emotional facets (urgency, confidence), logical facets
# (causality, specificity), and which genes would be activated

Run Accelerated Evolution

Train faster by running multiple generations against the same text

Instead of expressing one text at a time, use ace_genome_evolve to run multiple generations with mutation. This rapidly specializes the genome.

# Train a security-focused genome (10 generations)
ace_genome_evolve({
  text: "Zero-trust architecture. All service-to-service calls require
mTLS. Input validation at every boundary. SQL injection prevention via
parameterized queries. OWASP top 10 compliance mandatory.",
  agent_name: "security-agent",
  generations: 10
})

# Returns: initial state vs final state comparison
# Shows which traits strengthened (PRC, REG likely ↑) and weakened

Generations: Default is 5, max is 50. Higher = more specialized but more divergent from the parent genome.

Fork Specialist Agents

Create domain-specific children from your master genome

# Fork a security specialist with domain hints
ace_genome_fork({
  child_name: "security-specialist",
  parent_name: "master",
  domain_hint: "knowledge_guardian",
  mutation_rate: 0.01
})

# Fork a documentation specialist
ace_genome_fork({
  child_name: "docs-writer",
  parent_name: "master",
  domain_hint: "documentation"
})

# Fork without domain hints (inherits parent traits exactly + mutation)
ace_genome_fork({
  child_name: "project-alpha-agent",
  parent_name: "master"
})

24 Pre-built Domain Profiles

Security

Legal

Medical

Financial

DevOps

Frontend

Backend

Data Science

Creative

Architecture

Documentation

+12 more

Consolidate (Hive Mind)

Harvest strong genes from specialists back into the master genome

When specialist agents develop traits that exceed the master by 30%, consolidation transfers those gains back. This way all agents benefit from each specialist's experience.

# Run hive mind consolidation
ace_genome_consolidate()

# Returns: transfer records showing which genes were harvested
# from which specialists, and the divergence map

Tip: Run consolidation periodically (weekly or after intensive specialist training). The transfer uses a conservative 10% boost to prevent overcorrection.

Export & Import Genomes

Transfer behavioral DNA between environments

# Export genome as portable DNA string
ace_genome_export({ agent_name: "security-specialist" })
# Returns: { dna: "eyJnZW5lcyI6...", fingerprint: "a1b2c3..." }

# Import on another ACE instance
ace_genome_import({
  dna: "eyJnZW5lcyI6...",
  fingerprint: "a1b2c3..."
})
# Genome is registered and ready to use immediately

Use Cases

Move genomes between projects
Share trained agents with team members
Back up evolved genomes
Deploy to production environments

Integrity

The SHA-256 fingerprint verifies the genome wasn't tampered with during transfer. Import validates the fingerprint before registering.

Common Recipes

Practical workflows for genome evolution

Train a code review specialist

Fork from master with domain_hint: "qa". Then ace_genome_evolve with 20 generations of your team's PR review comments. The agent develops elevated PRC + REG.

Rapid specialization

Use ace_genome_evolve with 30-50 generations on representative text. Check ace_genome_state to verify traits shifted as expected. Repeat with different text samples.

Share trained genomes across team

Export with ace_genome_export, share the DNA string. Team members import with ace_genome_import. Everyone gets an agent trained on your domain instantly.

Reset and start fresh

Fork a new child from the default master genome. Your original master is always preserved — no risk of losing progress.

Related Guides

Agent Management Guide

Configure, run, and monitor agents

Agents + Genome

How agents and genomes work together

Full Reference

Traits, evolution lifecycle, FAQs