Things that cost a day to find out

Why these and not the others

The engine's own notes run to a couple of dozen entries, and not all of them belong on a public page. Two rules decide.

Published: what belongs to somebody else's library. How MLX behaves, what mlx-lm assumes, what a model's config.json can contain. That knowledge is not ours to keep — it is the cost of reading a library carefully, and anybody hitting the same wall is searching for it right now.

Kept: what is ours. The design of the paged cache, how sampling materialises candidates, the decision to slice before the final projection. Those took measurement to arrive at and they are the engine's advantage, not a general fact about MLX.

The line is not about secrecy for its own sake. It is that the first category is knowledge somebody else's users need, and the second is work.

Who these are for

Three kinds of reader, and the notes are written so that the first paragraph tells you which one you are.

If you are porting a model architecture — from mlx-lm, or from any reference implementation into any language — two of these are directly about the traps you will hit, and the third is about the boundary you will build to call your work from an application.

If you are using MLX from C or Rust rather than from Python, the loader note will save you a day, and the note on the C boundary is about a class of defect that gets worse the longer you go without checking for it.

If you are doing neither, one of them is still worth reading: the argument that a defect returning a plausible value costs more than one that crashes is not specific to inference engines, and neither is what follows from it.

What they are not

They are not tutorials. There is no getting-started material here, and none of them explain what a transformer is or how to install anything — that material exists, it is written well elsewhere, and repeating it would add pages nobody needs.

They are also not release notes. Nothing here announces a feature. Each one is a defect that took long enough to find that writing it down seemed cheaper than letting the next person spend the same day.

The rate at which these appear

Slowly, and that is deliberate rather than a shortage of material.

A note goes up when the defect is understood well enough to be stated in a sentence, and not before. Half the value of writing one is the forcing function: if the write-up needs three paragraphs of hedging to describe what went wrong, the investigation was not finished, and the right response is to go back and finish it rather than to publish the hedging.

That means there is no schedule. If you want to know when one appears, the subscription has a category for exactly this and nothing else.

A note on how these are verified

Every claim in these notes has a number or a reproduction behind it, and where a number appears it carries the date it was measured.

That is a habit this project learned expensively. Three figures written by hand in an internal document turned out, when measured again, to be 33 instead of 32, 26 instead of 24, and 1294 instead of 605 — the last wrong by more than double. A number in prose has nobody maintaining it. So the numbers here are dated, and if one of them has drifted, the date is the warning.