ENGINEERING · MAY 12, 2026 · 7 MIN READ
What discovery writes to the repo: HYRAX.md and the .hyrax bundle
Before remediation, Hyrax learns the codebase and commits what it learned — a HYRAX.md and a .hyrax context bundle any IDE assistant can read.
Most assistants relearn a codebase on every session. The understanding they build — which module owns what, where the conventions live, what the project is actually for — evaporates when the conversation ends. Discovery treats that understanding as an artifact worth keeping, and commits it to the repository.
Context belongs in version control#
If understanding a codebase is valuable, it should be durable, reviewable, and shared. The way to make any of those true is to write it to files and commit them. Discovery produces two things:
- HYRAX.md — a human-readable map of the project: structure, conventions, domain, and the facts an assistant needs to act without guessing.
- a .hyrax bundle — the supporting context that backs the map.
Both live in the repository. They show in diffs, they survive a restart, and a teammate who pulls the branch gets the same context the machine has.
HYRAX.md is not a private format#
A context file that only one vendor can read is a lock-in dressed as a feature. HYRAX.md is plain enough that any IDE assistant reads it directly — Cursor, Copilot, and Claude Code included. The file describes the project, not the tool that wrote it.
The bundle is
.hyrax/, and the map isHYRAX.md. Both are committed to the repository, so the team owns the context, not a session.
That choice has a practical payoff: the same map that makes Hyrax's remediation accurate also makes a developer's own assistant sharper, because they are reading the same ground truth.
Why files beat a session#
A session-bound context has three problems that files solve at once.
| Property | Session memory | Committed files |
|---|---|---|
| Survives restart | No | Yes |
| Visible in review | No | Yes |
| Shared across team | No | Yes |
None of these are exotic. They are the same reasons source code lives in a repo instead of an editor's undo history. Discovery applies that standard to context.
What this sets up#
With the map committed, everything downstream reasons from the same shared understanding. The audit knows what the project is. The fix pipeline knows the conventions a change has to respect. And the team's own tools read the file too, so the context Hyrax built does not stay locked to Hyrax.