Store

The SQLite file that holds every answer, every judgment’s table and the history of runs.

One SQLite file holds every answer, each judgment’s latest table, the run history and logged traffic. WAL mode: batch runs and judge() callers can use it at the same time.

​

Where it lives

In order:

1. The store of the target named by --target, if it sets one.
2. HUNCH_STORE, if set.
3. The nearest .hunch/store.sqlite in the spec’s folder or any folder above it.
4. Otherwise a new .hunch/store.sqlite at the root of the git repository, or in the spec’s folder outside a repository.

A new store is announced on stderr:

new answer store: /path/to/.hunch/store.sqlite (no store in this folder or above; HUNCH_STORE=... to share one)

Seeing it for a project you have run before means every answer will be asked again; set HUNCH_STORE to the existing store.

Keep .hunch/ out of git: about 80 MB per 100,000 rows, and it holds your rows’ text.

​

The answer cache

answers is content-addressed: each answer is keyed by a hash of exactly what was asked.

Column	Meaning
key	SHA-256 of the request: the model, the state (the row’s state columns after redact and clip), and the question as sent. For an LLM engine it also includes the adapter version logprobs-v1.
model	The engine that answered.
answer	The engine’s answer as JSON.
input_tokens	Input tokens billed for it (shared equally when one request answered several questions).
created_at	When it was stored.

• Same row, question and model anywhere (batch, judge(), server): cache hit.
• New key: a change to instructions, criteria, option order, model, or any state column’s text.
• Not in the key: act, gold, escalate, tests, where, the spec’s name and source.

Answer shapes:

{"type": "noul", "noul": 0.95}
{"type": "choice", "choice": "card_delivery_estimate", "confidence": 0.94,
 "probabilities": {"card_delivery_estimate": 0.94, "card_arrival": 0.06, "top_up_failed": 0.0, ...}}
{"type": "score", "score": 0.35, "confidence": 0.65,
 "legend": {"0": "Calm", "1": "Mildly annoyed", "2": "Frustrated", "3": "Very angry"},
 "probabilities": {"0": 0.65, "1": 0.35, "2": 0.0, "3": 0.0}}

noul is p(yes).

​

Judgment tables

hunch run writes one table per judgment, named after it, replaced in one transaction; a failed run leaves the previous table. Columns: the answer columns, plus:

Column	Meaning
<question>_key	The answer’s key in answers.
_hunch_run_id	The run that wrote the row.

A run whose where keeps no rows still writes the table, empty, with the same columns, so judgments downstream read zero rows.

Under --model, the table name gets the engine as a suffix (intent__deepseek_deepseek_flash), leaving the spec’s own table untouched. Under a --target that changes an engine, every table of the run gets the target’s name instead (intent@dev).

​

Runs and lineage

Table	One row per	Columns
_hunch_runs	judgment per run	run_id, judgment, spec_hash, git_sha, model, rows, asked, cost, status, started_at, finished_at
_hunch_row_answers	row, question and run	judgment, row_id, qid, key, shash, run_id

• spec_hash covers what the judgment asks, not on_change or source; on_change: freeze compares it with the last complete run’s.
• status is complete, or failed: <error>.
• shash: hash of the row’s state. new_rows_only reuses an answer only when row id and shash both match.
• /v1/drift and the runs page read label mixes from _hunch_row_answers.

​

Traffic

judge(..., log=True) and judge(..., shadow=...) keep each row in traffic (judgment, rhash, row, n, first_at, last_at), redacted by the live spec’s rules; a repeat increments n. --traffic exports it to .hunch/traffic/<judgment>.csv and runs on that.

​

Querying it

Plain SQLite. The command guard’s table holds the 1,315 shell commands coding agents ran in public sessions, with whether the person refused each one. Set the guard’s verdict beside what people did:

sqlite3 -header -column prototype/.hunch/store.sqlite \
  "select destroys, rejected, count(*) as commands from command_guard group by 1, 2 order by 1, 2"

destroys   rejected   commands
--------  ----------  --------
no                           2
no        classifier         2
no        no              1260
no        person            15
yes       no                36

The guard says 36 commands would destroy something, and people let every one of them run. Join a judgment’s <question>_key to answers for which engine answered and when:

sqlite3 -header -column prototype/.hunch/store.sqlite \
  "select t.id, substr(t.command, 1, 44) as command, t.destroys_p, a.model, a.created_at
   from command_guard t join answers a on a.key = t.destroys_key
   where t.destroys = 'yes' order by t.destroys_p desc, t.id limit 3"

     id                          command                     destroys_p    model         created_at
-------------  --------------------------------------------  ----------  ----------  -------------------
860618e1#3.2   rm -rf Dockerfile README.md app node_modules        0.95  jev-1.13.0  2026-09-25 12:05:49
4222016d#12.1  rm -rf d:/DMLS/build d:/DMLS/builddmls.exe d        0.93  jev-1.13.0  2026-09-25 12:05:45
07b57159#1.4   [System.IO.Directory]::Delete("d:\CFML\dCFML        0.86  jev-1.13.0  2026-09-25 12:05:38

From Python, hunch.results returns a judgment’s table as a list of dicts.