Self-Improvement

Harmonia can propose, validate, and apply changes to its own code and policy — under explicit safety gates with automatic rollback. This is a key differentiator from static agent frameworks: Harmonia does not just execute tasks, it evolves to execute them better.

Evolution Engines

Harmonia provides two complementary evolution modes, each targeting a different layer of the system.

Ouroboros (Source Rewrite)

Ouroboros handles Lisp-side evolution through the :source-rewrite mode. It maintains a crash history and patch artifact subsystem, enabling the agent to:

  1. Detect failures and performance degradation
  2. Analyze crash history to identify patterns
  3. Propose source code patches
  4. Validate patches against safety gates
  5. Apply changes or record failed attempts for future reference

The source-rewrite path modifies Lisp source files directly. All changes flow through ports/evolution.lisp to the lib/core/ouroboros Rust crate, which manages the patch artifact lifecycle.

Phoenix (Artifact Rollout)

Phoenix operates as the system supervisor (PID 1) and handles the :artifact-rollout evolution mode for Rust capability crates. It provides:

  • Hot-reload — swap compiled cdylibs without restarting the agent
  • Crash recovery — detect failures and restore the last known-good state
  • Artifact rollout — build, test, deploy, and monitor updated Rust crates
  • Automatic rollback — revert to the previous artifact on regression

Phoenix coordinates with lib/core/ouroboros and lib/core/phoenix through the Evolution port.

Three-Layer Evolution Model

Every piece of Harmonia's state falls into one of three layers with different mutability rules:

Layer What It Stores Mutability
Genomic Identity, creator lineage, DNA, constitutional constraints Non-negotiable. Cannot be modified by evolution engines.
Epigenetic Runtime policies, loaded modules, weights, hot patches Mutable under validation gates. Architecture-specific.
Versioned Memory Memory snapshots, experience logs, scoring history Freely mutable. Snapshotted for recovery.

The genomic layer is the identity core — it defines what Harmonia is and cannot be changed. The epigenetic layer defines how Harmonia behaves and is the primary target of evolution. Versioned memory captures what Harmonia has learned and feeds future improvements.

Version Snapshots

Evolution state is tracked through immutable version snapshots:

  • Current state: src/boot/evolution/latest/
  • Version history: versions/vN/ (one directory per version)

Each snapshot captures the full epigenetic state at the time of the change, enabling:

  • Point-in-time recovery to any previous version
  • Diff analysis between versions
  • Audit trail for all evolution decisions

Safety Gates

Every self-modification must pass through six safety layers before it is applied:

1. Constitutional Constraints

Genesis documents define immutable rules. No evolution can violate the DNA, creator lineage, or ethical constraints (all-species-respect, non-domination, human-care, truth-seeking, avoid-harm).

2. Matrix Route Constraints

The harmonic matrix enforces minimum harmony thresholds on all routes. A proposed change that would cause routes to fall below min_harmony is rejected.

3. Rewrite Validation Rules

Source rewrites are validated against structural and semantic rules before application. The modified agent must compile and boot successfully.

4. Recovery/Rollback Availability

No change is applied unless a rollback path exists. Phoenix maintains the previous artifact; Ouroboros maintains the previous source snapshot.

5. Production Readiness Checks

Changes are monitored post-application. Regressions in key metrics trigger automatic rollback.

6. Invariant Guards

Hard-coded invariants that cannot be weakened by any evolution path:

Invariant Value Purpose
Vault min_harmony >= 0.30 Prevents evolution from lowering the quality floor
dissonance-weight >= 0.05 Ensures injection patterns always carry meaningful penalty
Injection scanning Cannot be disabled Prevents evolution from removing security checks
*read-eval* on external data Cannot be enabled Prevents code injection through external input

Security Kernel Role in Evolution

The SignalGuard v6 security kernel gates all evolution operations:

  • Policy Gate (%policy-gate) — evolution operations are among the 14 privileged ops that require binary allow/deny authorization, checked against the taint chain and security label
  • Taint Propagation — evolution triggered by external signals carries the :external taint label through the entire reasoning chain via *current-originating-signal*, ensuring stricter validation
  • Safe Parsers — %safe-parse-number and %safe-parse-policy-value replace read-from-string throughout the evolution pipeline, preventing injection during patch parsing

Evolution proposals originating from external (user or frontend) signals face stricter gates than internally-generated improvements, because the originating signal's taint label persists through the entire decision chain.

Next Steps