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.
- Use it when a wrong or invented value would cause harm: who owns a program, what a budget is, which date was agreed, who the stakeholders are.
- Use something else when you want to control which rules and context your agent loads (
hero memory), or decide which tool calls are allowed (hero govern). - Alias: none.
- Reads or changes:
statusandlistread.addandremovechange your facts.project setchanges which project a folder belongs to, andadd --projectcan set it too.
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
| Subcommand | What it does | Reads or changes |
|---|---|---|
status | Your 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 |
list | Every 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
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--details | Flag | No | Off | None | Prints the fact sources and check-log counts instead of the default view. See the --details view. |
--json | Flag | No | Off | None | Prints the view as JSON. With --details, prints the details as JSON. See Example 5. |
Arguments for add
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<field> | Text | Yes | None | Any name, such as program_poc | The name of the fact. |
<value> | Text | Yes | None | Any value. Quote values that contain spaces. | The correct value. |
--project <name> | Text | No | Off: the fact is global | A project name | Makes 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> | Text | No | Off | A record domain | Advanced: files the fact under an explicit domain. Can't be used with --project. |
--alias <name> | Text, repeatable | No | None | Any name | Another name for the field, such as "program owner", so a reply that uses that name is checked too. |
--value-alias <value> | Text, repeatable | No | None | Any value | Another spelling of the value, such as Jane, that counts as correct. |
--type <type> | Choice | No | text | date, money, number, person, text | The 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. |
--complete | Flag | No | Off | None | Marks this value as the whole answer for the field. A reply that contradicts it is flagged as a record conflict. |
--id <id> | Text | No | <scope>.<field>.<value>, in lower case with other characters turned into - | Any id not already used | The id that remove takes. |
--replace | Flag | No | Off | None | Replaces the fact this field already has in this scope. Without it, a second value for the same field is refused. |
Arguments for list
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--project <name> | Text | No | Off: every fact | A project name | Shows only that project's facts. |
--stale | Flag | No | Off | None | Shows only facts past their freshness window. Facts added with hero record add have no freshness window, so they never appear here. |
Arguments for remove
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
<id> | Fact id | Yes | None | An id shown by hero record list | The fact to remove. |
Arguments for project
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
show or set | Choice | No | show | show, set | show prints this folder's project. set names it. |
<name> | Text | With set | None | A project name | The 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.
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.Check what your agent is checked against.
hero record listYou should see a
Globalgroup with your fact and its id.Use your agent as you normally do, then see what it got wrong.
hero recordYou should see
YOUR FACTS,WHAT THE AGENT GOT WRONGandRECOMMENDATION.
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
| Section | What it shows |
|---|---|
YOUR FACTS | How 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 WRONG | How 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. |
RECOMMENDATION | The next thing to do, with the command to run. |
| Line | What it means |
|---|---|
✗ <n> replies contradicted your facts | Replies 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 sets | The project's value applies there, so these aren't counted as contradictions. |
✓ <n> consistent with your facts · <n> not about your facts | Replies that agreed with your facts, and replies that didn't mention them. |
! <n> actions used a value your facts don't allow | Tool 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
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | Done | The view printed; a fact was added or removed; a project was shown or set. | Nothing. |
1 | Not done | A 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. |
2 | Refused | An 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. |
3 | Facts or check log can't be read | status 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. |
| Error | Cause | Fix |
|---|---|---|
hero record add: <field> already has a fact here (<id> = <value>) — two values for one field would both read as correct. Replace it: add --replace | The 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 written | The 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 retry | The 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
| Name | Kind | Purpose |
|---|---|---|
HERO_HOME | Environment variable | Root of Agent OS's files on your machine. Default ~/.hero. |
$HERO_HOME/records/global.json | File | Global facts added with hero record add. |
$HERO_HOME/records/project-<name>.json | File | One project's facts, added with --project. |
$HERO_HOME/records/user.json | File | Facts added with --domain. |
$HERO_HOME/records/*.json | Files | Every 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.json | File | An older single-file form, still read, after records/. HERO_RECORD_PATH names another file for it. |
$HERO_HOME/record-projects.json | File | Which folder belongs to which project. |
$HERO_HOME/record-log.jsonl | File | The 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_OFF | Environment variable | Set to 1, true, yes or on to stop adding facts to prompts and checking replies. |
Limits of hero record
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| Replies are flagged, not blocked | A reply that contradicts a fact is shown to you and the agent is asked to correct it. The reply itself isn't stopped. | No | Read WHAT THE AGENT GOT WRONG. |
| Codex replies | Checked 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 Codex | Upgrade Codex, then run hero setup. |
| Facts per prompt | At 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. | No | None. |
| What counts as a contradiction | A 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. | No | Add --alias and --value-alias for the names and spellings your team uses. |
What remove can remove | Only facts added with hero record add. Facts in other source files stay. | No | Edit that file. |
| Freshness | Facts added with hero record add have no freshness window, so list --stale never shows them. | No | None. |
| Output size | The text views print at most 16 KiB. | No | Use --json for everything. |
Commands related to hero record
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.