Harmonia Agent

Harmonia is a recursive self-improving autonomous agent built on SBCL Common Lisp with Rust capability libraries connected via C-ABI/CFFI. It orchestrates tasks, evolves its own source code, and converges toward optimal performance through harmonic scoring — all under explicit safety gates with automatic rollback.

What Is Harmonia

Harmonia plans and executes complex tasks, scores outcomes across multiple dimensions, and iteratively rewrites its own code and policies to improve over time. The Lisp orchestrator handles reasoning, memory, and evolution while 37 Rust crates (18 core + 3 backends + 6 tools + 10 frontends) provide all I/O and computation through 9 explicit FFI port boundaries.

The name reflects the core mechanism: harmony is measurable orchestration quality. The agent scores every interaction and routes decisions through a harmonic matrix with minimum-harmony thresholds, converging toward stable high-performing configurations.

Unlike conventional agent frameworks that rely on static prompts and manual tuning, Harmonia proposes, validates, and applies changes to its own source code — autonomously and continuously — through two evolution engines: Ouroboros (source rewrite) and Phoenix (artifact rollout).

Design Principles

Three principles from Vitruvius guide every architectural decision:

Principle Meaning In Practice
Firmitas (Strength) Resilience and recovery Every change has a rollback path. Phoenix supervises as PID 1 with crash recovery. Vault enforces min_harmony >= 0.30.
Utilitas (Utility) Clear task completion Deterministic tick model. Minimal, composable orchestration. Direct tool dispatch for internal prompts.
Venustas (Beauty) Clean, maintainable structure Explicit 9-port FFI boundary. Declarative S-expression configuration. Transparent harmonic scoring.

How Harmonia Differs

  • Self-improving — rewrites its own Lisp source (Ouroboros) and rolls out Rust binaries (Phoenix) under safety gates
  • Harmonically scored — routes are gated by effective_signal >= effective_noise && harmonic >= edge.min_harmony
  • Security kernel — SignalGuard v6 with typed signal dispatch, binary policy gate, taint propagation, and safe parsers
  • 10 frontends — TUI, Telegram, Slack, WhatsApp, iMessage, Mattermost, Nostr, Email, MQTT, Tailscale
  • Deterministic tick model — per-tick cycle: gateway-poll, process-prompt, memory-heartbeat, harmonic-step, gateway-flush
  • DNA & Constitution — genomic identity layer with ethical constraints (all-species-respect, non-domination, truth-seeking, avoid-harm)

License

Business Source License 1.1 (BUSL-1.1). Source code is available and readable. Change Date is 2030-03-05, at which point the license converts to Apache 2.0.

Install

macOS / Linux / FreeBSD / NetBSD:

curl -sSf https://harmoniis.com/harmonia/install | sh

Windows:

iwr https://harmoniis.com/harmonia/install.ps1 -UseB | iex

From source:

cargo install harmonia && harmonia setup

Prerequisites: Rust 1.75+, SBCL, Quicklisp (auto-installed by the setup wizard).

Quick Start

After installation, run the setup wizard:

harmonia setup

The wizard will:

  1. Create the system workspace at ~/.harmoniis/harmonia/
  2. Ask for your user workspace directory (default: ~/workspace)
  3. Verify SBCL and Quicklisp are available
  4. Prompt for your OpenRouter API key (stored encrypted in vault)
  5. Select frontends to enable
  6. Collect frontend credentials
  7. Build and configure

Then start the agent:

harmonia start

Supported Platforms

Platform Architectures
macOS Apple Silicon, Intel
Linux x86_64, aarch64
FreeBSD x86_64
NetBSD x86_64
Windows x86_64

Next Steps