03 // Developer Tooling
Lease — $300 / project
HESUS
A Development Brain for AI-Assisted Software
An AI coding session has no memory. Every new conversation re-derives your project from scratch — and on a real codebase that re-derivation burns most of a context window before any work starts. Worse, the constraints that never made it into the code — never log payloads, this table is append-only, zero the key material — are invisible, so a fresh session cheerfully violates them.
HESUS is a portable project brain you fold into any codebase. It carries the architectural decisions — the why this, why not that — as durable, queryable objects, and hands the AI exactly the governing decisions, files, and constraints for the task at hand. Drop it in, run one command, and it reads your project cold and writes its own configuration. Measured: 89% less context than reading the source, zero retrieval degradation to 1,000 decisions, and 88% of safety constraints surfaced across 30 adversarial tasks. Pure standard-library Python. No dependencies, no API key, no telemetry.
Drop-In · Any Repo
20 Empirical Studies
Pure Python · stdlib only
Zero Runtime Deps
Self-Configuring
Context-Efficient
// Why It Works
The scarce, irreplaceable asset in a long-lived codebase isn't the code — code can be regenerated. It's the decisions: why a boundary was drawn here, why an approach was rejected, what a subsystem is actually for. That reasoning is exactly what disappears between AI sessions, between team members, and between the person who wrote a module and the person who has to change it six months later. HESUS treats those decisions as first-class, retrievable objects rather than prose buried in commit messages and wikis that drift out of sync with the code.
Engine & data, strictly separated
The brain is project-blind — it hardcodes no fact about any codebase. A project's knowledge lives entirely in data the engine reads through a descriptor. That's why one engine serves any project, and why the engine can be upgraded underneath a project without touching accumulated knowledge.
It assembles and points; you judge
HESUS doesn't think for you. Briefed on a task, it surfaces the decisions and files that bear on it and points at the full sources — deliberately not paraphrasing. Judgment, work, and bug-catching stay with the operator. No false authority, no single point of failure.
Cold until needed
The expensive operations — gestating a project's history, planning an upgrade — are gated behind necessity checks and run rarely. Day-to-day orientation is cheap. The steady state pays almost nothing, so it's practical to live with rather than a tax on every session.
// How It Configures Itself
The hard part of any tool like this is setup. HESUS removes it. On first contact it gestates its own configuration from a cold read of your project — and it's honest about how it knows each thing:
Probe
Facts it can see: your root marker, source language, where docs live, the id-prefixes your docs already use. It looks and fills them.
Propose
Where no signal exists yet, it offers the smallest sensible default and marks it “correct me” — never a heavy guess dressed up as fact.
Accrete
Lived history — the decision graph itself — starts empty and grows. It never fabricates. An empty field is honest, not a gap.
If your project already tracks decisions (ADR files, an RFC directory, a structured DECISIONS.md), HESUS adopts it — becoming a lens on the memory you already keep — rather than imposing a parallel store. Only when it finds no convention does it create a fresh one. Adopt is the default, because it's humbler and lower-friction.
// Five Organs, Adopted As You Grow
The brain is organized by cognitive function, not by file type. You don't need all of it on day one — you climb a maturity ladder as the project earns each rung.
I · Memory
The knowledge cortex: a structured decision graph, queryable, that holds why each boundary was drawn and each approach rejected.
II · Immune
The guards: project-specific checks that catch regressions and dishonest code — stubs that look like real work.
III · Attention
The context budget: cheap orientation, danger-file warnings, scope contracts — so a session doesn't burn its context before it works.
IV · Conscience
Honesty enforcement: every TODO, stub, and unverified claim is a ranked promise, never silently dropped.
V · Nervous
Handoff and projection: one-way rendering of the cortex into readable prose, and session handoff artifacts.
The ladder
Seed → Sapling → Tree → Forest. Start with the irreducible three organs; the brain tells you when you've grown enough to advance.
The central daily benefit is context-efficient briefing. Instead of an AI session cold-reading a project's entire decision history to orient — burning a large fraction of its working context — one brief returns only the governing decisions, the files to read in full, and the constraints in play. Because a brief stays near-constant in size while the cortex grows, the saving grows as the project accumulates more decisions. Under the hood it's about 6,200 lines of standard-library Python across single-purpose organs, reading every project-specific through one descriptor seam — and it ships a fallback TOML parser so it needs zero pip installs and runs on Python 3.8+.
// What Ships In The Box
The brain is not just a CLI. Everything below runs on the standard library, offline, with no API key, no service, and no telemetry — deterministic tools you can read the source of.
A dashboard, not a config file
A zero-dependency web console served from Python itself: 12 tabs over the decision graph — browse and search the cortex, run a brief and see it rendered, read the code with its debt markers, view the studies with their charts, see coverage gaps, steer the AI, and switch between brains. Double-click to launch.
It grades its own retrieval
A coverage report shows which load-bearing decisions have no trigger vocabulary declared — the ones retrieval will miss — and proposes candidate terms from the concern they guard. In a blinded review, 100% of the generated candidates were accepted, and the accepted terms measurably carried recall.
A confidence line that means something
Every brief is graded quiet / caution / low-confidence from the retrieval's own signals. This was calibrated as a classifier against labeled probes, not guessed. Silent misses — a thin answer that still looked confident — went from 61% to 0%. When it doesn't know, it says so.
A research subsystem
The engine carries the lab that built it: a protocol for falsifiable studies, real effect-size statistics (Cliff's delta, a "wins X% of the time" figure, and a significance check) translated into one plain-English verdict, SVG charts, and a cold archive that costs zero context until you open it.
Provenance you can audit
Decisions bind to a git commit and blob id, so the brain can detect when the code a decision governs has drifted underneath it — hard identity, no name-matching guesswork. Git-optional by construction: no repo, clean no-op.
It ships honestly or not at all
A ship gate runs the checks, a smoke test imports every organ and runs every verb, and a self-check reconciles every part against the manifest. An engine upgrade that would silently drop a capability is refused — a rule written in blood after it happened once.
// What It Measures Out At
89%
context saved versus reading the source to reconstruct the same constraints — break-even on the first pass
0
retrieval degradation from 40 to 1,000 decisions — the scale ceiling is a plateau, not a cliff
88%
of safety constraints surfaced across 30 adversarial tasks, on the hardest domain it has faced
These come from 20 pre-registered empirical studies run across 154 build passes — on synthetic testbeds, on a hand-rolled binary-protocol codec the engine was never tuned for, and on Omniscient, a real shipping Windows fleet-hardening tool carrying 326 live architectural decisions. Not benchmark fixtures built to flatter the system. The studies that failed are on the record too, below.
// The Evidence, In One Table
Every engine decision is driven by a study. Each one is a falsifiable hypothesis, pre-registered before the run, measured with real statistics, and archived — including the studies that refuted the idea being tested.
What was measuredResult
Context cost of a brief versus reading the source (6 passes, 70-decision project)11.2% of the cost — 89% saved
Retrieval as the cortex grows — 40 to 1,000 decisions100% / 90% — zero degradation
Safety constraints surfaced across 30 adversarial tasks on a binary-protocol codec88% (29 of 33)
A six-step cascading build where each mistake feeds the nextFirst domino caught — 5 downstream violations prevented
Naive violations prevented on a real 326-decision production project9–11 of 20
Cross-pass contradictions, head-to-head with the brain and without it3 → 1; rationale preserved 0/20 → 20/20
Silent misses — a thin answer that still looked confident61% → 0%
Can any zero-dependency trick close the remaining paraphrase gap?No — refuted, and the code was deleted
The last row matters as much as the others. Four candidate mechanisms were built to close a known weakness; none cleared the pre-registered bar, so all of them were removed from the engine and the negative result was written down. That is the standard the whole system is held to.
// The Research Behind It
HESUS wasn't tuned by feel. Its retrieval — the part that decides which decisions a brief surfaces — was developed as a chain of pre-registered experiments against a frozen set of labeled probes: one falsifiable hypothesis at a time, method and metrics fixed before the run, measured with real statistics (effect size, a plain-English "wins X% of the time," and a significance check), then archived. Twenty studies now sit behind the engine.
22 → 43/45
frozen-probe retrieval recall across the research arc — measured, not asserted
13 → 67%
hard adversarial recall after the author-declared trigger-terms lever
33 → 93%
load-bearing decision recall after a ranking fix proven by a 2×2 factorial
Each gain came from a specific, disconfirmable change. The trigger-terms field was inert without the field, so the control cell reproduced exactly — that is what a clean experiment looks like. A ranking hypothesis was confirmed by a 2×2 factorial before it shipped, and the rival hypothesis in the same factorial was refuted. A separate precision audit then confirmed those recall gains were not bought with precision. And the whole study archive is cold storage: it costs zero context during normal operation — the research never taxes the tool.
// Where It Proved Itself Honest
The studies that went against the product are the ones worth reading:
It invalidated its own headlineTwo early studies reported 100% retrieval recall. A later, harder study proved that number was an artifact of easy probes — real paraphrase already lost a third of recall. The rule fired, the old headline was retracted by its own author, and the harder 45-probe set became the permanent baseline every later fix had to beat.
It deleted code that didn't workFour zero-dependency mechanisms were built to close the paraphrase gap. Pre-registered bar: recover at least half the gap. None did. Two were refuted outright and removed from the engine; one shipped as an optional flag at a measured 25%. The negative result was recorded rather than buried, and the remaining limit is stated plainly instead of engineered around with a number that flatters.
It corrected its own scale claimAn early result showed retrieval falling off a cliff at 1,000 decisions. Re-run with honest probes, the cliff disappeared — it had been a flaw in the test, not the engine. The corrected finding (zero degradation) replaced it, and the original error is still on the record.
A real saveA brain migration once passed three green gates and still silently dropped three organs. That incident became a permanent capability-audit gate that now refuses a migration which would lose an organ — because green gates only verify what they were built to verify.
// What Is Proven, And What Is Not
ProvenContext efficiency (89% saved, break-even on pass one, and the advantage widens as the project grows). Scale (zero retrieval degradation to 1,000 decisions; still interactive at ~114ms). Constraint surfacing on adversarial tasks (88% on a domain the engine was never tuned for) and on a real 326-decision production codebase (9–11 of 20 naive violations prevented). Cascade prevention — catching the first mistake in a six-step chain stopped all five that followed.
ConditionalThe consistency benefit is bounded by retrieval, and retrieval is bounded by vocabulary. A recorded constraint only helps if the brief surfaces it for the tempting task. When the task and the decision share no words — "cache the parsed chain" versus "zero key material from memory" — it can still miss. Declaring trigger terms closes most of that gap; nothing closes all of it. Ingest quality is the ceiling.
Not yet provenEvery study was authored and audited by the same intelligence that ran it. Violations are assessed, not observed in the wild by an independent, blinded agent. A proper multi-agent randomized trial has not been run, and until it is, the behavioral lift is recorded as modeled, not demonstrated. Said plainly, because that is the whole point.
HESUS does not autonomously write code or make decisions. It makes an operator's judgment durable, queryable, and provenance-preserved. Sold as exactly that, the measured results above are what it delivers.
$300 / project — one-time
A "project" is one codebase the brain is folded into and grows with: seeded or gestated on arrival, accumulating that project's decisions over its life, upgradeable to newer engine generations without losing what it has learned. Folded in once, it's yours to keep in that codebase for life. Pure Python, standard library only, no external dependencies — it runs anywhere your code does and adds nothing to your runtime.
