Module 2 · Tools, Knowledge, Memory & Research Design · scripted
Abstraction: Briefing in Apples
Two compactions of the same history
The compaction move we just built produced a record: what was done, what was decided, what remains. For many tasks that is exactly right. But watch a case where it quietly isn't. A coding agent has spent 60 iterations building a sensor-data ingestion service — designing, writing, refactoring, fixing. The wall is full. Two different summarizers compact the same history:
Compaction A · the record
BRIEFING: Built ingestion for the buoy network. Iterations 1–14: set up project, chose Postgres. 15–31: wrote CSV import for the wave-height sensors, fixed timestamp bugs. 32–44: added the JSON feed for the weather buoys; refactored shared parsing. 45–60: validation added after bad readings crashed the store; parsing moved out of the API layer. REMAINING: support the new acoustic sensors (binary format).
Compaction B · the model
Compaction B · the invariants
Both are honest. Both fit on one page. Now give each briefed agent the same next task and watch the difference:
Add support for the acoustic sensors — binary format, spec attached.
⟨tool_use⟩
edit_file(path = "api/handlers.py", old = "…", new = "def
receive_acoustic(payload): readings = parse_binary(payload);
db.insert(readings)")Add support for the acoustic sensors — binary format, spec attached.
⟨tool_use⟩
create_file(path = "adapters/acoustic.py", content = "# adapter #3:
binary → readings, emits to validator …")I've added the acoustic adapter following the pipeline: it parses the binary format and emits standard readings to the validator — nothing else touches the new format, and the store still has a single writer.
Record vs. model
A RECORD is organized by the past: what happened, in order. A MODEL is organized by the domain: how to think about what's next. A record INFORMS the remaining work. A model GOVERNS it.
The second framing
Name what Compaction B really did: it changed the representation. We learned earlier that the description chooses the solution — polar coordinates make the circle easy — and that the first framing is chosen before the conversation begins. Compaction is the one moment in a trajectory where you get to choose the coordinate system again, and this time with the benefit of everything the conversation has learned. Sixty iterations ago, nobody knew the architecture. Now it's known — and the compacted wall can be built out of it.
The second framing
Compaction doesn't have to shrink the old representation. It can REPLACE it — with the representation the remaining work deserves, chosen in hindsight.
Write the briefing in apples
Now the second move, and it reaches back to the beginning of our tool-design work. Recall the word apple: one small token, and an information-dense structure unfolds — looks, weight, uses — learned long before the conversation began. We used that to price tool names. But the same economics govern every word on the wall, including every word of a briefing. Compare two ways to convey the same architecture:
The same knowledge, priced two ways
IN EPLES (described from scratch) ~95 tokens "The system is organized so that business logic never touches the database directly; instead, access goes through objects that expose collection-like operations, and the core logic is kept independent of the web framework and storage so each can be swapped; state changes are captured as a sequence of events rather than updates in place…"
IN APPLES (named) ~14 tokens "Hexagonal architecture. Event-sourced. Repository pattern — no ORM types outside the repositories."
…and the named version is BETTER, not just cheaper: each name unfolds into more trained structure than the paragraph managed to describe — edge cases, conventions, standard mistakes included. The description is a translation bill. The name is a paid-up account.
The design rule for every abstraction you write:
The apple principle, generalized
The best compression is a pointer into what the model already knows. Write the briefing in apples, not in eples: name every pattern that HAS a name, and spend description only on what is genuinely novel.
The engineered apple
What about structures that have no standard name? Then you choose an apple to borrow: a metaphor. A good metaphor imports a whole trained bundle of entailments in a handful of words. Watch one do real reasoning work:
Our results cache works like this — it's in your briefing: "the cache is a coat check: storing returns a ticket; retrieval requires the ticket; the cloakroom is small." A user reports their report link failed with "result not found" after lunch. What happened, and what should the retry logic do?
The cloakroom is small — coats get cleared out to make room when new ones arrive. The user's result was evicted while they were at lunch; their ticket is valid but the coat is gone. Retry logic: never treat the ticket as a guarantee. On "not found," regenerate the result, store it again, and hand back the new ticket — and for anything a user might return to hours later, persist it properly instead of leaving it at the coat check.
Apples decompress more than you asked for
And that is also the danger. The thrown apple came with affordances nobody stated — that was the magic — but wrong names ship wrong affordances with exactly the same silence. Call your buffer a "queue" and the model assumes first-in-first-out; if it isn't, you have re-created the lying name — this time in your briefing instead of your tool set. The disciplined pattern is the one experts use on each other:
Name, then deviate
The name pays for 95% of the structure. The exception clause costs one line. Never let the name promise something the system doesn't keep.
- In Example 2, list three entailments of "coat check" that are true of the cache — and invent one that could be false. What would the agent do wrong because of it?
- What's the "coat check" of your own research domain — the metaphor your field uses to brief newcomers in one line? What does it get slightly wrong?
The three registers
Step back, because this completes a ladder we started building back with the Tolstoy manual. There are three registers for putting knowledge into a conversation, in increasing order of density:
Describe · exhibit · point
Choosing a register is a lookup question: is this pattern trained? Point at it. Merely demonstrable? Exhibit it. Genuinely novel? Then you must describe it — and pay full price. A well-built abstraction usually uses all three: names for the known patterns, one worked example for the house style, description only for the truly local rules. That mix — not any single register — is what makes a one-page briefing able to stand in for sixty iterations.
What abstraction is
Compaction asks: what can we DROP? Abstraction asks: what can we POINT TO instead of carry? The lightest context is not a shorter transcript. It is a better representation — written in words that were paid for during training, not during the task.
Return to the compaction you built in the earlier fork — and redo it as an abstraction. (1) Choose the representation the remaining work deserves: a diagram, a schema, a set of invariants — not a timeline. (2) Name every nameable pattern in it; count the tokens you just stopped paying. (3) Engineer one metaphor for a structure with no standard name — and write its deviation clause. (4) Run both briefings on the same next task and compare what each agent built: which one's work is cohesive with everything that came before?