Ekamyth Agent OS docs
Added for agents / Gets smarter

hero learn

Shows what Ekamyth Agent OS has learned from your agent's real outcomes on this machine, what is still gathering evidence, and whether anything is shared.

What hero learn does

It answers one question: what has Agent OS learned from my agent's real work, and is any of it in use? Agent OS learns from outcomes, not content: which model did each kind of work well, whether cheaper models held up when a call was replayed on one, and when a rule Agent OS turned into code fell back to the model. The screen is titled Improve. For each learner it shows what was learned, how many outcomes it rests on, and whether it's active, still gathering evidence, or not learning yet. Learning stays on this machine unless you opt in to sharing content-free outcomes.

Limit: it learns only from model calls through the model gateway, over the last 30 days. See Limits.

Synopsis for hero learn

hero learn [status] [--json | --details]
hero learn --help

Run with no subcommand, it behaves as status. Any other flag is refused with learn has no flag '<flag>' and exit code 2. hero learn --help describes the default view only. hero learn demo needs an examples package that isn't installed, so it isn't documented here.

Subcommands of hero learn

SubcommandWhat it doesReads or changes
statusEach learner, what it learned and its status; what is shared; and what to do next. This is the default.Reads

Arguments for hero learn

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--jsonFlagNoOffNonePrints the view as JSON. See Example 1.
--detailsFlagNoOffNonePrints the count of recorded corrections and fallbacks instead of the view. Text only, even with --json.

How hero learn gets its answer

It reads three records on your machine: the record of model calls through the model gateway over the last 30 days, the learning log of corrections and fallbacks, and the local buffer of outcome samples. From them it builds one row per learner:

LearnerWhat it learnsWhen it's active
route · model choiceWhich model does each kind of work well, from real outcomes.A kind of work and model pair turns quality-aware once it has 10 outcomes. Until then the pair is pending.
route · downgrade checksWhether cheaper models hold up on your work: how many replays on a cheaper model matched the requested model.Active from 10 judged replays; pending below that.
correctionsYour corrections and the agent's fallbacks, from the learning log.Not learning in this build.
memory · rule picksWhich rules matter for which prompts.Not learning in this build.
autonomy · trustWhat your agent may do without asking.Not learning in this build. Trust is earned in hero autonomy.

The title names the window it actually read: Improve · no outcomes read, or Improve · outcomes <from> → <to> UTC.

Get started with hero learn

Before you start: Agent OS is installed, hero setup has run, and your agent's model calls go through the model gateway. These commands work the same on Mac and Linux.

  1. See what has been learned.

    hero learn

    You should see WHAT HERO LEARNED FROM YOUR OUTCOMES, SHARED WITH CORE and RECOMMENDATION.

  2. If every learner reads not enough data, run your agent through Agent OS and check again later.

    hero run claude

Example output of hero learn

Output from version 0.1.36rc13 on a new install, with no model calls yet.

Improve · no outcomes read
WHAT HERO LEARNED FROM YOUR OUTCOMES
  ┌──────────────────────────┬────────────────────────────────────┬──────────┬────────────────────┐
  │ learner                  │ what it learned                    │ outcomes │ status             │
  ├──────────────────────────┼────────────────────────────────────┼──────────┼────────────────────┤
  │ route · model choice     │ which model does each kind of work │ 0        │ not enough data    │
  │                          │ well                               │          │                    │
  ├──────────────────────────┼────────────────────────────────────┼──────────┼────────────────────┤
  │ route · downgrade checks │ whether cheaper models hold up on  │ 0        │ not enough data    │
  │                          │ your work                          │          │                    │
  ├──────────────────────────┼────────────────────────────────────┼──────────┼────────────────────┤
  │ corrections              │ your corrections and the agent's   │ 0        │ not enough data    │
  │                          │ fallbacks                          │          │                    │
  ├──────────────────────────┼────────────────────────────────────┼──────────┼────────────────────┤
  │ memory · rule picks      │ which rules matter for which       │ —        │ not learning       │
  │                          │ prompts                            │          │                    │
  ├──────────────────────────┼────────────────────────────────────┼──────────┼────────────────────┤
  │ autonomy · trust         │ what your agent may do without     │ —        │ not learning       │
  │                          │ asking                             │          │ (after govern)     │
  └──────────────────────────┴────────────────────────────────────┴──────────┴────────────────────┘
  nothing learned — Hero learns locally from your agent's real calls, corrections
  and fallbacks; no events so far

SHARED WITH CORE
  not shared — learning stays local, on this machine
  local samples: 0 verified · 0 completed (quality unknown)
  not shared: downgrade quality · real-work outcomes for route
  what is collected and what left this machine: hero privacy

RECOMMENDATION
  → run your agent through the Ekamyth Agent OS — Hero learns from its real calls:
    hero run <agent>
  details: hero learn --details

How to read hero learn output

The status column

StatusWhat it meansWhat to do
activeThe learner has enough outcomes and is in use. For model choice, the row names how many pairs have quality-aware picks on.Nothing.
pending proofOutcomes are building up but aren't enough yet. For model choice, each pair needs 10.Keep working.
not enough dataNo outcomes yet.Run your agent through Agent OS.
not learningThis learner doesn't learn in this build.None.
unavailableYour call history couldn't be read, so learning is unknown, not zero. The screen adds check: hero health.Run hero health.

Shared with Core

Without sharing, it reads not shared — learning stays local, on this machine. local samples counts the outcome samples kept on this machine. The not shared: line lists outcomes this build doesn't send.

The recommendation

One next step: run your agent through Agent OS when there's no data, keep working while pairs are pending, or, when learning is running, nothing to do.

More hero learn examples

Example 1. To use the view in a script

hero learn --json

It prints one JSON object: learners (each with learner, learned, outcomes, status and, when not learning, why), core (shared, buffered, policy_at, policy_version, unreadable, delivery, sample_basis) and window. When recent model calls haven't been read in yet, it adds partial_reasons.

Example 2. To count corrections and fallbacks

hero learn --details

Output from version 0.1.36rc13 on a new install. The path is shortened.

learn — correction capture · fallback detection · server-side policy update
  no events yet — corrections and fallbacks are recorded as they happen  (~/.hero/learn-log.jsonl)

With events, the second line reads <n> correction(s) · <n> fallback(s) recorded.

Exit codes and errors for hero learn

CodeMeaning for this commandCauseWhat to do
0DoneThe view printed, including when nothing has been learned or the call history couldn't be read.Read the status column.
2RefusedAn unknown subcommand or flag.See the errors below.
ErrorCauseFix
learn has no flag '<flag>'An unknown flag. Exit 2.Check the synopsis.
learn has no verb '<word>'An unknown subcommand. Exit 2.Check the synopsis.

Files and environment for hero learn

NameKindPurpose
HERO_HOMEEnvironment variableRoot of Agent OS's files on your machine. Default ~/.hero.
$HERO_HOME/meter.jsonlFile, readThe record of model calls. HERO_METER_LOG names another file.
$HERO_HOME/learn-log.jsonlFile, readCorrections and fallbacks, content-free. HERO_LEARN_LOG names another file.
$HERO_HOME/samples.jsonlFile, readThe local buffer of outcome samples. HERO_SAMPLE_LOG names another file.

Limits of hero learn

LimitBehaviourCan you change it?What to do
What it learns fromModel calls through the model gateway, over the last 30 days. Calls that don't reach the gateway aren't seen.NoRun your agent with hero run.
Evidence neededA model choice pair needs 10 outcomes, and downgrade checks need 10 judged replays, before they're active.NoKeep working.
CorrectionsNothing in this build records corrections, so the corrections row counts fallbacks only.NoNone.
Learners not activememory · rule picks and autonomy · trust don't learn in this build.NoNone.
Learning stays localLearning stays on this machine. Downgrade quality and real-work outcomes for routing aren't sent in this build.NoSee hero privacy for what Agent OS can send from this machine.

Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.