Data files
What Ekamyth Agent OS keeps on your machine, in its folder, and why. Each file is read by a command you can run.
Where Agent OS keeps its data
In ~/.hero, or the folder HERO_HOME names. Agent OS creates the folder readable by your user only (mode 0700), and narrows an existing one to that. The files below are the ones you may want to look at: the ones the commands in these docs read and write. Agent OS keeps other internal files in this folder too; they aren't listed here. For what leaves your machine, see How Privacy works.
Agent OS also writes into your agents' own folders when you run hero setup: the settings and hooks in ~/.claude/settings.json and ~/.codex/config.toml and ~/.codex/hooks.json, the slash commands in ~/.claude/commands/hero/, and the skills in ~/.agents/skills/hero-<name>/ and the skills folder under your Codex home. See Agent settings that hero setup writes.
Records of what your agents did
| File | What it holds | Read by |
|---|---|---|
meter.jsonl | One line per model call through the model gateway. The fields include task_class, model, provider, request_fp, usd, in_tokens, out_tokens, reasoning_tokens, ok, ts, latency_ms, call_id, request_id, routed_from, accepted, reason, tokens_saved, usd_saved and schema_version. This isn't the complete list. request_fp is a hash of the request, not the prompt. Older rows can lack newer fields, and some optional fields are left out. | hero efficiency, hero route, Monitor |
meter.db | The same model-call records in a database, beside meter.jsonl, kept for 365 days so a long export can read them. | hero efficiency, hero route, Monitor |
trace.db | The steps of each session. | hero trace |
shared-truth.db | Shared records that Monitor and Control read, such as usage facts and their daily totals. | Monitor, Control; hero status checks it |
attest.jsonl | The hash-chained record of decisions, without the content of prompts or replies. | hero attest |
verdict-log.jsonl | How each job ended. | hero verdict |
egress.jsonl | What Agent OS recorded as sent off your machine. | hero privacy |
Rules and decisions
| File | What it holds | Written by |
|---|---|---|
registry.json | Your registered rules. | hero init |
govern.json | Your action policy. See Settings. | You, hero govern init and hero govern add |
inbox.json | Actions held for your decision. | The hooks; read by hero inbox |
schedules.json | The standing jobs and their cadence. | hero schedule |
brain/ | Your Brain's files. | hero brain |
Setup records and logs
| File | What it holds | Used by |
|---|---|---|
skills-install.json | Which command files setup installed in your agents, so it can check and remove them. | hero setup --check, hero setup --undo |
proxy.log | The model gateway's request log. | hero health, hero route census |
proxy-restart.log | The model gateway service's restarts. | The model gateway service writes it |
portal.log | The Portal's log. | The background Portal writes it |
schedule.log | The scheduler service's log. | The background scheduler writes it |
proxy.json | The model gateway's port, and the address hero setup pointed your agents at. | Every hero command; hero setup --check |
preview-access.json | This machine's activation record. hero setup --undo removes it. | hero setup, hero status (access row) |
install.json | This install's random id, behind the code hero support prints. | hero support |
archive/ | Compressed archives of old session records, with a sha256 for each. | Written by hero prune |
Editing these files
Change rules and policy with the commands, not by editing these files. Your agent can't edit govern.json, registry.json, inbox.json, schedules.json or skills-install.json: the hooks refuse it. Hand edits to files in ~/.hero aren't supported, so use the commands.
How long Agent OS keeps data
| Data | Kept for | Change it with |
|---|---|---|
Individual model-call records in meter.jsonl | 90 days, then archived when hero prune runs. meter.db keeps them for 365 days. | HERO_METER_RETENTION_DAYS |
| Session records | 14 days, then archived to archive/ and deleted when hero prune runs. Archives expire after 90 days. | HERO_ACTIVITY_RETENTION_DAYS keeps more. HERO_TRACE_LEVEL sets how much each keeps. |
| Everything else | Nothing expires on its own. hero prune never prunes the attest record or the job verdict log, and leaves your Brain's files alone. |
hero prune also runs weekly as a standing job; see hero schedule. Removing Agent OS leaves this folder in place. See Remove Agent OS.
Related
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.