Self-Tuning

A MUXI formation observes its own activity and periodically distills what it learns into durable behavioral guidance. That guidance lives in a file called MUXI.md at the formation root - the formation's "captain's log" of learned behavior - and it steers the overlord and agents on every subsequent turn.

Self-tuning is on by default. Every formation improves out of the box; you can dial it down or turn it off with the tuning: block.

How the loop works

A single in-runtime job runs on a schedule (once a day by default) and makes two passes:

1. Digest - it reads the event spool accumulated since the last checkpoint and aggregates it into a compact activity report, then checkpoints. The digest is also stored as a formation-scope Captain's Log entry and injected into every user's context as the "Formation operations log."
2. Tune - it reads that digest, recent log entries, and past experiments, detects patterns, and distills behavioral learnings into a candidate revision of MUXI.md. Learnings whose watched metric never moved are retired. A short "morning report" summarizes what changed.

Depending on auto_apply, a candidate revision is either applied directly to MUXI.md or written alongside it as PENDING-MUXI.md for you to review.

Configuration

The top-level tuning: block controls the loop. An absent block means "on with defaults":

tuning:
  active: true            # Off switch: false disables the loop entirely
  interval_hours: 24      # How often the loop runs (default: 24)
  auto_apply: true        # Apply revisions directly, or hold them as pending

Shorthands:

tuning: false             # Same as { active: false }

Invalid values fail fast at formation load, never at tuning time.

The tuning files

Both files are runtime-owned state. When you redeploy or roll back a formation, the server preserves the live MUXI.md and PENDING-MUXI.md (just like memory.db) so an update never wipes what the formation has learned. See Managing Formations.

Reviewing suggestions from the CLI

When auto_apply is off, the CLI lets you inspect and act on the pending suggestion:

# Review the live and pending state
muxi tuning show        # Display the live MUXI.md
muxi tuning pending     # Display the pending suggestion, if any

# Act on the pending suggestion
muxi tuning apply       # Promote the pending suggestion to the live MUXI.md
muxi tuning dismiss     # Discard it (dismissed learnings are never re-proposed)

The morning report can also carry an apply/dismiss widget, so a review can happen inline in a chat channel as well as from the CLI.

When the commands: block is enabled, the deterministic /learnings command provides the same chat surface:

/learnings
/learnings pending
/learnings apply
/learnings dismiss

apply and dismiss are refused in multi-user mode because they change formation-wide guidance; operators must use the admin tuning API instead.

API surface

The same state is available over the admin API (all paths under /v1, admin key required):

Applied learnings are injected into the overlord's context via the captain's-log layer, so guidance steers every turn without re-reading the whole file.

Benchmark-driven observation

When MUXI_BENCH_ROOT is set, the tuning loop also observes benchmark runs rooted there, folding their outcomes into the digest so learnings can be correlated against reproducible benchmark metrics rather than live traffic alone.

Learn More

• Managing Formations - how tuning state survives updates
• Formation Schema - the full configuration surface
• Observability - the event spool the digest reads from