Ekamyth Agent OS docs
Reference / Data files

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

FileWhat it holdsRead by
meter.jsonlOne 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.dbThe 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.dbThe steps of each session.hero trace
shared-truth.dbShared records that Monitor and Control read, such as usage facts and their daily totals.Monitor, Control; hero status checks it
attest.jsonlThe hash-chained record of decisions, without the content of prompts or replies.hero attest
verdict-log.jsonlHow each job ended.hero verdict
egress.jsonlWhat Agent OS recorded as sent off your machine.hero privacy

Rules and decisions

FileWhat it holdsWritten by
registry.jsonYour registered rules.hero init
govern.jsonYour action policy. See Settings.You, hero govern init and hero govern add
inbox.jsonActions held for your decision.The hooks; read by hero inbox
schedules.jsonThe standing jobs and their cadence.hero schedule
brain/Your Brain's files.hero brain

Setup records and logs

FileWhat it holdsUsed by
skills-install.jsonWhich command files setup installed in your agents, so it can check and remove them.hero setup --check, hero setup --undo
proxy.logThe model gateway's request log.hero health, hero route census
proxy-restart.logThe model gateway service's restarts.The model gateway service writes it
portal.logThe Portal's log.The background Portal writes it
schedule.logThe scheduler service's log.The background scheduler writes it
proxy.jsonThe model gateway's port, and the address hero setup pointed your agents at.Every hero command; hero setup --check
preview-access.jsonThis machine's activation record. hero setup --undo removes it.hero setup, hero status (access row)
install.jsonThis 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

DataKept forChange it with
Individual model-call records in meter.jsonl90 days, then archived when hero prune runs. meter.db keeps them for 365 days.HERO_METER_RETENTION_DAYS
Session records14 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 elseNothing 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.

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