Skip to content

The record

The record is the .rb/ folder at the root of your repository: plain YAML files you commit with your code.

Every item is its own file, and every experiment has its own folder:

.rb/project.yaml the project: its title, where it was cloned from
.rb/notes/<id>.yaml one file per note on the project
.rb/questions/<id>.yaml what the work is trying to find out
.rb/experiments/<id>/experiment.yaml an experiment: its questions, purpose, hypothesis, shared settings, freeze
.rb/experiments/<id>/variants/<name>.yaml one file per variant: its role and its own settings
.rb/experiments/<id>/notes/<id>.yaml one file per note on the experiment
.rb/experiments/<id>/criteria/<id>.yaml one file per criterion
.rb/experiments/<id>/runs/<id>.yaml one file per run, with its receipt
.rb/experiments/<id>/analyses/<id>.yaml one file per analysis
.rb/metrics/<id>.yaml the metric catalogue
.rb/resources/<id>.yaml datasets, checkpoints, code
.rb/decisions/<id>.yaml calls, each with who made it, why, and what it was made on
.rb/log.jsonl every write: who made it, in which chat session, how, and the hash of what was written
.rb/cache/ local copies, kept out of git

Two branches that add runs write different files, so they merge without a conflict.

A run’s receipt names its command and commit. A criterion is a rule a result must meet (Criteria), and its finding is what rb works out from the runs. A call is a decision on the work, such as accepting a result (Calls).

rb spec set records a setting with the file that states it, such as a config key (configs/train.yaml#optim.lr) or a table row (results/sweep.csv#[precision=int8].calib). rb reads the source on the spot. The source must name the setting: resnet50 does not state 50, and adamw does not state adam. A comment never counts. When the source states the value, rb keeps the text it read, the file’s hash and the commit.

Other settings are provisional (given but not checked, such as a web address), unknown (nobody has found it) or inherited (from a cloned record).

rb checks the sources again on every read. A source that states another value is a conflict, and one that no longer states it is stale. Both are problems on every finding of that experiment.

To check what a run used, record it with its resolved config (rb run add ... --config out/seed1/config.yaml). A run whose config disagrees with the recorded settings is shown and not counted.

rb never refuses a write because of who makes it. Every write records who made it (you, or the agent rb detects), the chat session and model when the agent gives them, and the reason given.

This is in rb log --json, a command’s --json output and .rb/log.jsonl. Screens such as rb status and rb open never show it. They do show agent work that waits for your approval with rb confirm, such as “design not confirmed”.

rb never stores findings, or the state of experiments and questions. It computes them on every read. If a page you were sent disagrees with rb status, rb status is right.

Never edit .rb/ by hand. A run changed outside rb is not counted, and every finding that depends on a changed file lists the problem. Adding a comment or reformatting does not count as an edit.

rb doctor lists changed files. rb doctor --restore puts back what rb last wrote. rb doctor --adopt --why "..." keeps the change and records who adopted it.

A file that is not a valid record stops rb status, rb show and every --fail-on gate with E_STATE_CORRUPT, and rb says where it breaks.

rb says how git holds the record, in words such as “all record files committed” or “2 record files not committed”. rb status says it under the title, and the details further down:

Terminal window
$ rb status
…
rb checked the record with git at 2026-11-10 15:32 UTC: all 13 record files are new, changed or deleted since commit 234b05955a46, which does not hold the record.
Not committed: .rb/.gitattributes (new), .rb/.gitignore (new), .rb/experiments/smooth/criteria/smoothing-helps.yaml (new) and 10 more
To check it yourself, in your terminal: git -C ~/vit-smoothing status --short --untracked-files=all -- .rb
…

Every rb status says what rb looks at:

Terminal window
$ rb status
…
rb looks in out/, outputs/, results/, eval-out/ and metrics/ at the top, in folders named for results (results/, eval/, metrics/, reports/, artifacts/ and the like), down to 4 levels from the top, at the files in the repository's top folder, and at .json, .yaml and .toml files git shows as new or changed. It last looked at 2026-11-10 15:32 UTC. It reads what code, configs, docs and database rows say only where the record points to them, and it sees only the commands run through rb journal run.
…

rb also looks in any folder a recorded run named. rb reconcile lists results nobody recorded, each with the rb run add line that records it. rb reads no run from a report in prose, such as RESULTS.md.

Each row of a CSV, TSV or JSON Lines table is a run. rb run add <exp> --from results.tsv --where <column>=<value> records one. --every-row records every row --where picks as its own run, and reads a SQLite table the same way (--from results.db --table evals). Record one table of many runs and Record a folder per run show both layouts.

Each file opens with its format, rb: 1 or rb: 2. Only a criterion whose rule is a count, a best of N, a relative change or a cited difference of means is written in format 2 (Criteria).

Both formats are one JSON Schema, rb-v2.schema.json. rb schema all prints it, and The record’s format lists every kind.

Rabbit Brainrabbitbrain.ai · GitHub · PyPI · Privacy · Apache-2.0