Ekamyth Agent OS docs
Added for agents / Done means done

hero record

Keeps the facts your agent must get right, gives them to your agent with each prompt, and flags any reply that contradicts them.

What hero record does

It answers one question: is my agent stating my facts correctly? You record the facts that matter, such as a program owner, a budget or a launch date, with hero record add. Through the hook that hero setup installs, Ekamyth Agent OS adds the relevant facts to each prompt, then checks your agent's reply when the turn ends. A reply that contradicts a fact is flagged and the agent is asked to correct it. Tool calls are checked against your facts too. The check is deterministic and uses no model. Your fact values stay on this machine: the check log records field names, verdicts and digests of values, never the values themselves.

Limit: replies are flagged, never blocked. Claude Code replies are checked once hero setup has connected it; Codex replies once hero setup connects its Stop hook, which needs Codex 0.114.0 or later. See Limits.

Synopsis for hero record

hero record [status] [--details] [--json]
hero record add <field> <value> [--project <name> | --domain <domain>] [--alias <name>]...
                [--value-alias <value>]... [--type date|money|number|person|text]
                [--complete] [--id <id>] [--replace]
hero record list [--project <name>] [--stale]
hero record remove <id>
hero record project [show]
hero record project set <name>
hero record --help
hero record add|list|remove|project --help

Run with no subcommand, it behaves as status. hero record --help describes status only; each of add, list, remove and project prints its own options with --help. hero record demo needs an examples package that isn't installed, so it isn't documented here.

Subcommands of hero record

SubcommandWhat it doesReads or changes
statusYour facts, what the agent got wrong, and what to do next. This is the default.Reads
add <field> <value>Adds a fact. It applies to every session unless you give --project.Changes
listEvery fact your agent is checked against, global facts then each project's, with each fact's id.Reads
remove <id>Removes a fact you added with hero record add.Changes
project [show]Prints which project the current folder belongs to.Reads
project set <name>Sets the current folder to project <name>, so that project's facts apply here.Changes

Arguments for hero record

Arguments for status

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--detailsFlagNoOffNonePrints the fact sources and check-log counts instead of the default view. See the --details view.
--jsonFlagNoOffNonePrints the view as JSON. With --details, prints the details as JSON. See Example 5.

Arguments for add

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
<field>TextYesNoneAny name, such as program_pocThe name of the fact.
<value>TextYesNoneAny value. Quote values that contain spaces.The correct value.
--project <name>TextNoOff: the fact is globalA project nameMakes the fact apply in that project only. A project fact outranks a global fact for the same field. Can't be used with --domain. See How projects work.
--domain <domain>TextNoOffA record domainAdvanced: files the fact under an explicit domain. Can't be used with --project.
--alias <name>Text, repeatableNoNoneAny nameAnother name for the field, such as "program owner", so a reply that uses that name is checked too.
--value-alias <value>Text, repeatableNoNoneAny valueAnother spelling of the value, such as Jane, that counts as correct.
--type <type>ChoiceNotextdate, money, number, person, textThe kind of value. money and number are stored as a number: commas and $ are removed, and a value that isn't a finite number is refused.
--completeFlagNoOffNoneMarks this value as the whole answer for the field. A reply that contradicts it is flagged as a record conflict.
--id <id>TextNo<scope>.<field>.<value>, in lower case with other characters turned into -Any id not already usedThe id that remove takes.
--replaceFlagNoOffNoneReplaces the fact this field already has in this scope. Without it, a second value for the same field is refused.

Arguments for list

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
--project <name>TextNoOff: every factA project nameShows only that project's facts.
--staleFlagNoOffNoneShows only facts past their freshness window. Facts added with hero record add have no freshness window, so they never appear here.

Arguments for remove

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
<id>Fact idYesNoneAn id shown by hero record listThe fact to remove.

Arguments for project

ArgumentTypeRequiredDefaultAllowed valuesWhat it does
show or setChoiceNoshowshow, setshow prints this folder's project. set names it.
<name>TextWith setNoneA project nameThe project to set this folder to.

How hero record gets its answer

Giving facts to your agent. When you send a prompt, the hook adds a short block of facts that are in scope for this folder: your global facts and this project's facts. It adds at most 40 facts or 800 tokens. Facts named in the prompt, or in this session's recent prompts, are always included.

Checking the reply. When the turn ends, the hook checks the reply against every fact in scope, not only the ones it added. A claim that's clearly about a fact and gives a different value is a contradiction. A claim it can't tie to a fact with confidence is left unverified, never counted as wrong. For a contradiction, Agent OS asks the agent to correct its reply and shows hero record — the reply contradicted a recorded fact; the agent was asked to correct it. If anything goes wrong during a check, the turn goes ahead unflagged.

Checking tool calls. Before a tool call runs, the hook compares the values in the call with your facts and records any mismatch.

How projects work. A folder belongs to the project you set with hero record project set. If you haven't set one, it belongs to the project named after its git repository's root folder, or else after the folder itself. hero record add --project <name> also sets the current repository to that project, unless the folder already belongs to another project that has facts of its own, or isn't in a git repository. It never sets your home folder or a folder above it. The output says which happened.

The status view. status reads your facts and the check log on your machine. If either can't be read in full, it refuses with exit 3 rather than show a count of zero.

Get started with hero record

Before you start: Agent OS is installed and hero setup has connected Claude Code or Codex. These commands work the same on Mac and Linux.

  1. Add a fact your agent must never get wrong.

    This command will:

    • add one global fact to your facts file on this machine.
    hero record add program_poc "Jane Smith" --alias "program owner"

    You should see added global.program-poc.jane-smith: program_poc = Jane Smith · global — every session, then a line about whether replies are being checked yet.

  2. Check what your agent is checked against.

    hero record list

    You should see a Global group with your fact and its id.

  3. Use your agent as you normally do, then see what it got wrong.

    hero record

    You should see YOUR FACTS, WHAT THE AGENT GOT WRONG and RECOMMENDATION.

Example output of hero record

Output from version 0.1.36rc13 on a new install, before any fact was added.

Record · facts your agent must get right · all retained
YOUR FACTS
  Record has nothing to check against. Add your first fact (--project <name> for
    one project only):
    hero record add <field> <value>

WHAT THE AGENT GOT WRONG
  no replies checked yet. Claude Code replies are checked once hero setup has
    connected it.

RECOMMENDATION
  → add a fact your agent must never get wrong, e.g.:
    hero record add program_poc "Jane Smith" --alias "program owner"
  Codex replies are checked once hero setup connects its Stop hook (Codex
    0.114.0 or later); tool actions are checked too.
  every fact: hero record list
  store details: hero record --details

Example output once replies have been checked. The format is the command's; the numbers are examples. Trimmed where you see …

Record · facts your agent must get right · all retained
YOUR FACTS
  2 facts · global 1 · project acme-calc 1
…
WHAT THE AGENT GOT WRONG — 42 replies checked
…
  ✗ 2 replies contradicted your facts (2 values)
  ✓ 12 consistent with your facts · 28 not about your facts
  replies are flagged, never blocked
…

How to read hero record output

The default view

SectionWhat it shows
YOUR FACTSHow many facts you have, by scope, and how many are past their freshness window. Sources that couldn't be read, and duplicate facts, are marked !. For a duplicate, the copy read earlier is the one checked.
WHAT THE AGENT GOT WRONGHow many replies were checked, how many contradicted your facts, how many were consistent, and how many weren't about your facts. It also counts tool calls that used a value your facts don't allow, and replies that weren't checked because your facts couldn't be read at the time.
RECOMMENDATIONThe next thing to do, with the command to run.
LineWhat it means
✗ <n> replies contradicted your factsReplies that gave a different value for a fact. The agent was asked to correct each one.
? <n> replies differed from a global value on a field a project setsThe project's value applies there, so these aren't counted as contradictions.
✓ <n> consistent with your facts · <n> not about your factsReplies that agreed with your facts, and replies that didn't mention them.
! <n> actions used a value your facts don't allowTool calls with a mismatched value, and which check, if any, refused them.
<n> checked replies on the local attest chain (tamper-evident)Each checked reply is also written to the local record that hero attest verify checks.

The --details view

Output from version 0.1.36rc13 on a new install.

  record — output gate · action gate · source sync · correction capture
  ──────────────────────────────────────────────────────────
  store           empty — add your first fact: hero record add <field> <value>
  ────────────────────────────────────────────────────────
  events          0  — Claude Code replies are checked once hero setup has connected it; Codex replies once hero setup connects its Stop hook (Codex 0.114.0 or later)
  ──────────────────────────────────────────────────────────

With facts and checks recorded, store shows the fact count and each source file with its count and when it was updated. events is followed by output gates (buffered and streaming), action gates, syncs, replies checked, conflicts (marked ⚠ review when any), and last event. A source that can't be read is listed as corrupt/incompatible. The view prints at most 16 KiB; longer output ends with a line saying how many bytes were left out.

More hero record examples

Example 1. To add a fact for one project

hero record add budget 250000 --project acme-calc --type money --complete

It prints added project-acme-calc.budget.250000: budget = 250000 · project:acme-calc · complete, then which folder the fact applies in, such as this folder (acme-calc) is now project acme-calc, so these facts apply here.

Example 2. To list your facts

hero record list

Example output. The format is the command's; the values are examples.

Global
  global.program-poc.jane-smith                program_poc = Jane Smith  (also: program owner)
Project acme-calc
  project-acme-calc.budget.250000              budget = 250000  (complete)

With no facts, it prints no facts recorded — add one: hero record add <field> <value>.

Example 3. To change a fact's value

hero record add program_poc "Ana Ruiz" --replace

It replaces the global program_poc fact. Without --replace, the command is refused, because two values for one field would both read as correct.

Example 4. To remove a fact

hero record remove global.program-poc.jane-smith

It prints removed global.program-poc.jane-smith.

Example 5. To use the view in a script

hero record --json

It prints one JSON object with title and data. data carries facts (total, groups, stale), the reply counts (replies, replies_wrong, replies_consistent, replies_other), the action counts, problems (every flagged check, with field and verdict but no value), store_issues, log_lines_skipped, replies_attested and attest_chain. hero record --details --json prints store, check_log and unavailable instead.

Example 6. To see which project this folder is

hero record project

It prints project <name> · set it: hero record project set <name>.

Exit codes and errors for hero record

CodeMeaning for this commandCauseWhat to do
0DoneThe view printed; a fact was added or removed; a project was shown or set.Nothing.
1Not doneA fact already exists, a facts file can't be read or written, the fact to remove wasn't found, or the folder-to-project map can't be read.See the errors below.
2RefusedAn unknown subcommand or flag, a missing argument, a value that isn't a number for --type money or number, or project set with no name.Check the synopsis.
3Facts or check log can't be readstatus couldn't read your facts or the check log in full; list couldn't read a fact source.Run hero record --details to see which.
ErrorCauseFix
hero record add: <field> already has a fact here (<id> = <value>) — two values for one field would both read as correct. Replace it: add --replaceThe field already has a value in this scope. Exit 1.Add --replace, or remove the old fact.
hero record add: a fact with id '<id>' already exists — remove it first: hero record remove <id>The id is in use. Exit 1.Remove it, or give another --id.
hero record add: <id> was not added with `hero record add` — change it in its own source--replace on a fact that came from another source file. Exit 1.Edit that file.
hero record add: <file> is unreadable (<issue>) — nothing writtenThe facts file for that scope can't be read. Exit 1.Fix or move the file.
hero record add: '<value>' is not a number supported by storage — nothing written--type money or number with a value that isn't a number. Too large or not finite reads differently. Exit 2.Give a plain number.
hero record remove: no fact '<id>' among the facts added with `hero record add`No such id in the facts hero record add wrote. Exit 1.Copy the id from hero record list.
hero record list: <n> fact source(s) could not be read — …A facts file can't be read, so the list is incomplete. Exit 3.Fix the file or its permissions; see the ! lines.
usage: hero record project set <name>project set with no name. Exit 2.Give the name.
hero record project: <why> — fix or remove it, then retryThe folder-to-project map can't be read. Exit 1.Fix or remove record-projects.json.
record has no flag '<flag>'An unknown flag for status. The rule line reads hero record takes: [status] [--details] [--json]. Exit 2.Check the synopsis.
record has no verb '<word>'An unknown subcommand. Exit 2.Check the synopsis.

Files and environment for hero record

NameKindPurpose
HERO_HOMEEnvironment variableRoot of Agent OS's files on your machine. Default ~/.hero.
$HERO_HOME/records/global.jsonFileGlobal facts added with hero record add.
$HERO_HOME/records/project-<name>.jsonFileOne project's facts, added with --project.
$HERO_HOME/records/user.jsonFileFacts added with --domain.
$HERO_HOME/records/*.jsonFilesEvery JSON file here is read as a fact source, by file name in order. When two sources hold the same fact, the earlier one is used and the other is listed as a duplicate.
$HERO_HOME/record.jsonFileAn older single-file form, still read, after records/. HERO_RECORD_PATH names another file for it.
$HERO_HOME/record-projects.jsonFileWhich folder belongs to which project.
$HERO_HOME/record-log.jsonlFileThe check log: field names, verdicts and value digests, never values. HERO_RECORD_LOG moves it, and the records/ folder and project map move with it.
HERO_RECORD_OFFEnvironment variableSet to 1, true, yes or on to stop adding facts to prompts and checking replies.

Limits of hero record

LimitBehaviourCan you change it?What to do
Replies are flagged, not blockedA reply that contradicts a fact is shown to you and the agent is asked to correct it. The reply itself isn't stopped.NoRead WHAT THE AGENT GOT WRONG.
Codex repliesChecked only once hero setup connects Codex's Stop hook, which needs Codex 0.114.0 or later. Codex tool calls are checked either way.Yes, by upgrading CodexUpgrade Codex, then run hero setup.
Facts per promptAt most 40 facts or 800 tokens are added to a prompt. Facts named in the prompt or in recent prompts are never left out. Every reply is still checked against every fact in scope.NoNone.
What counts as a contradictionA claim must be clearly about the fact and give a different value of the same kind. Anything less certain is left unverified, not counted as wrong.NoAdd --alias and --value-alias for the names and spellings your team uses.
What remove can removeOnly facts added with hero record add. Facts in other source files stay.NoEdit that file.
FreshnessFacts added with hero record add have no freshness window, so list --stale never shows them.NoNone.
Output sizeThe text views print at most 16 KiB.NoUse --json for everything.

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