How the Harness works

The Harness is about 10,000 lines of JavaScript with no dependencies, and two compact data files. It has no server, no index and no model of its own, and it keeps nothing unless you ask. It can be that small because it doesn't search everything on every turn: a person narrows things down first, and each turn only chooses from what is left.

One turn

A learner writes "i got 2/5".

1. What the teacher decided is already a short list: a goal, how far the AI may go, perhaps a standard, a few misconceptions and some guidance from research.
2. The moment is read: giving an answer, asking for the answer, stuck, or trying again.
3. The list is cut down to this moment: one teaching move, and at most two of each other kind.
4. Instructions are written from the teacher's words and the resources' own text, never the learner's, so what a learner types can change what is chosen but can't write instructions.
5. Your model replies, with those instructions after your own system prompt.
6. check and record, if you want them: a second model reviews the reply, and a record says what went in.

const turn = await prepare({ teaching, message, history });
turn.instructions;   // what goes after your system prompt
turn.moment;         // "attempt"
turn.chosen;         // which misconceptions, skill components and guidance it took

Two stages, which is why there is no vector store

What is chosen for an activity is kept as it was, with where it came from. A run never waits on a far-off service, and a record can say exactly what the AI was given.

The pool

How a turn chooses

By rules, with no model call and no cost. Patterns read the moment, in English. A list item is taken when it shares at least two words with what was just said, the closest first. Guidance can name its moments, and then those for the moment take turns as the conversation goes on, so a learner doesn't hear the same two every time.

By a small model, for one more call a turn (pickerModel). It reads the conversation and the numbered list, and answers which to take. It reads any language, and more of the moments. If it fails or takes too long, rules decide.

How well this works so far: of 30 moments a small model read 29 and rules read 23, but finding the right misconception for a message worked on only 4 of 19 turns (what was measured). That is the weakest part, and the evaluation looks at it first.

Keywords, embeddings and RAG

The Harness does no retrieval. A list of a dozen items needs no index, and everything above it was narrowed by a person.

Retrieval is for your own documents, such as a library's guides, and belongs to whatever holds them:

Using both generally finds more than keywords alone: meaning catches a paraphrase, and keywords catch an exact name or a code. The space is rarely the issue: a vector of 1,024 numbers is 4 KB, so 10,000 passages are 40 MB, and a class's guides are hundreds of passages.

Giving the misconceptions vectors too is possible, at about 32 MB and an embedding model on every turn. It isn't built, and whether it would beat a small picker model is for the evaluation to say.

Skills, MCP and the gateway

All of them reach the same code. What differs is what runs where, and whether it's guaranteed to run.

Where the Engine and the Developer Platform use it

Neither has a copy: they import these same files, so a change here reaches all three.

Why it is this small

• It lends nothing out and keeps nothing: a host passes in fetch, a model and a store.
• It has no dependencies, so what you install is what you see: 0.8 MB packed.
• It holds decisions, not knowledge: the data it carries is small and compact, and what is large stays with its makers until someone asks for it.

This page comes from the open repository: harness/docs/how-it-works.md. To change it, change it there.