Advanced Guide

Genome Evolution

Starter+

Let the AI Genome Lab evolve your namespace's cognitive DNA: observe, evolve, ground, consolidate. A controlled loop for improving agent behaviour without guessing.

What is the AI Genome Lab?

Configurable “DNA” for your agents, with an evolution loop backed by the Observer

Every ACE3 namespace has a genome — a structured configuration that governs how agents reason, prioritise, and act. The genome is made of 8 gene types, each controlling a different cognitive dimension:

Gene	What it controls
`orchestration`	How agents coordinate and sequence work
`memory`	What gets remembered, consolidated, or forgotten
`attention`	Where agents focus during multi-task runs
`reasoning`	Planning depth, tool selection, branching
`risk`	Caution vs speed on ambiguous actions
`knowledge`	How context is retrieved and weighted
`communication`	Style, verbosity, and escalation behaviour
`learning`	How feedback updates the genome

You can edit genes manually, but that requires domain intuition. The evolution loop lets the Observer agent propose improvements based on what it's learned from real agent runs, then validates those improvements before they go live.

Viewing your current genome

Dashboard or MCP

Dashboard

Open /dashboard/genome. You'll see a radar chart of all 8 genes with their current values, a history timeline showing past mutations, and buttons to evolve, fork, and ground.

MCP

ace_genome_state(namespace="my-project")

# Returns current genome with all 8 genes, current generation,
# last evolution timestamp, and stability score

The evolution workflow

Observe → Evolve → Ground → Consolidate

Evolution is a four-step loop. Each step is an MCP tool you can call explicitly, or trigger from the dashboard.

1Observe

The Observer agent watches your agents run and records what works and what doesn't. It builds a hypothesis: “agents using genome X get better outcomes than agents using genome Y on tasks of type Z”.

You don't call this directly — it runs in the background. But you can inspect its observations with ace_review_observations(namespace).

2Evolve

Run N generations of mutation + selection against the current genome. Each generation tries gene variations and scores them against Observer signals.

ace_genome_evolve(
  namespace="my-project",
  generations=3,
  selection_pressure=0.3  # how aggressively to discard weak mutations
)

This consumes LLM quota because mutations are scored via LLM judgement. Start small (generations=3) and iterate.

3Ground

Validate the evolved genome against real operations BEFORE it becomes active. The grounding phase runs a test battery (configurable) against the candidate genome and reports any regressions.

ace_genome_ground(namespace="my-project")

# Runs validation tests against the evolved candidate
# Returns: { passed, failed, regressions, net_improvement }

4Consolidate

If grounding passes, consolidate merges the validated improvements into the active genome. If it fails, the candidate is discarded and the active genome stays put.

ace_genome_consolidate(namespace="my-project")

# Merges the grounded candidate into the active genome
# Previous genome is archived (rollback available via fork)

Forking for safe experimentation

Copy a genome to a new namespace to experiment without risk

Running evolution directly on your production namespace is risky. Instead, fork the genome into a fresh test namespace, run experiments there, compare outcomes, and only port successful mutations back.

# Fork genome from production to an experiment namespace
ace_genome_fork(
  source_namespace="my-project",
  target_namespace="my-project-experiment"
)

# Evolve the experiment aggressively
ace_genome_evolve(
  namespace="my-project-experiment",
  generations=10
)

# Compare outcomes
ace_genome_state(namespace="my-project")
ace_genome_state(namespace="my-project-experiment")

Rollback on a bad experiment is trivial: just delete the experiment namespace. Your production genome never changed.

Export & import — portability

Move a genome between namespaces, environments, or orgs

Genomes are portable JSON. Export from one namespace, import into another. Useful for backups, cross-environment promotion (dev → staging → prod), or sharing a tuned genome between projects.

# Export
ace_genome_export(namespace="my-project")
# → returns portable JSON (all 8 genes, generation, metadata)

# Import (into a different namespace, org, or server)
ace_genome_import(
  namespace="my-project-v2",
  genome_json=<exported JSON>
)

Coming (Plan #317): Passport-signed genome packages. Export a genome signed with your Passport key, import on a different org with cryptographic proof of origin. Enables agent portability across environments.

Evolution vs manual tuning

When to let the system learn, when to tune by hand

Use evolution when

• You don't know the right gene values
• Agent behaviour is inconsistent across similar tasks
• You want to explore a large configuration space
• The Observer has accumulated enough observations to have opinions

Use manual tuning when

• You have strong domain intuition (dev workflow, risk tolerance)
• The change is small and targeted (one gene)
• You're reverting a specific mutation
• The Observer has limited data (new namespace)

Safety notes

Things to know before running evolution

• Evolution consumes LLM calls. Each generation scores mutations via LLM judgement. generations=10 can burn meaningful API quota. Start with 3, review, then iterate.
• Always fork first. Run experiments on a forked namespace, not production. Rollback is free.
• Grounding is not optional. Skipping ace_genome_ground lets untested mutations into your active genome. Don't.
• Observer needs data. On a brand-new namespace with zero observations, evolution has nothing to optimise against. Run the namespace normally for a while first.
• Genome anchoring. Use ace_anchor (coming in Plan #190 follow-up) to pin specific genes that must not mutate during evolution.

Try an evolution run

Fork your genome into an experiment namespace, run three generations, inspect the grounding report, and see if the Observer found something you missed.

Related: Agents • Agents + Genome • QCMM Research