--- title: The Library Behind The Agent type: deep-dive level: L2 status: live revision: 1 updated: 2026-08-17 systemVersion: 4.2 tags: [architecture, library, decision-making, deep-dive] rating: 7.80 ratingAxes: useful 8 · evidence 9 · pull 7 · original 8 · form 7 ratingKind: derived source: library_citations.log (144 entries) + library_lookup.py + doctrine history --- # The Library Behind The Agent _Written 2026-08-17 · last verified 2026-08-17 · system v4.2 · live_ **TL;DR** — The agent keeps a library of 123 real books plus 4 periodicals, retrieved by a weighted keyword index rather than embeddings. A citation log of 144 real entries shows roughly 84% of consultations changed how a task was actually done; the rest are logged as ignored rather than deleted. The system went through one real failure — a lookup tool that scored 93% on two-word queries and 37% on natural sentences — and one real doctrine change, after the first version optimised for citation frequency and produced exactly the decorative quoting it was meant to prevent. ## What it is 123 books plus 4 periodicals, organised into 19 clusters — strategy, pricing, supply chain, negotiation, data analytics, and so on. Every book that counts as "in the library" has three things: the full text as markdown, a one-page brief, and a trigger card (keywords, mental models, one line on when it applies). A PDF sitting on disk without those three is not in the library — the lookup tool cannot find it, and for this system that means it does not exist. ## How retrieval works No vector database, no embeddings, no similarity search. A keyword index over the trigger cards, weighted — trigger phrases and title count 3x, mental models and the one-line hook count 2x, the cluster name counts 1x. A query like *"how do I structure a price increase without losing the account"* gets tokenized, matched against all 127 cards, and returns the top 3. The reason is the same one behind this system's memory layer generally: retrieval was never the interesting problem. Knowing which framework actually *applies* was. A vector search returns the closest match; it has no opinion on whether the match is decoration or a genuine fit for the situation. That judgment call — the **Framework-Fit Gate** — happens after retrieval, not instead of it: before applying a book's method, check whether the context actually matches the book's assumptions. A blind application of a good framework to the wrong situation is a worse failure than using no framework at all. ## The number that mattered: not citations, but method changes The first version of this system measured how often a book got cited per session and set a floor — roughly one citation per business conversation. It produced exactly what you'd expect from optimising a proxy metric: books got quoted at the end of an answer that had already been decided some other way. A decorative citation. The fix wasn't a better floor. It was changing what gets logged. Every consultation now records one of four outcomes — `accepted`, `rejected`, `ignored`, `tbd` — and the honest answer is a first-class outcome, not a failure to suppress: ``` 2026-08-14 | Reconciling supplier invoicing — mapped clusters, but the task was pure numeric reconciliation | none — hook fired, book not used | ignored ``` Across 144 logged consultations, roughly **84% ended `accepted`** — the book changed a method, a sequence, or a decision rule, not just the wording of an answer. The rest are kept, not deleted. A citation log that only records successes is measuring its own confidence, not its own accuracy. ## What actually gets cited, and how often The most-consulted books by logged count: Cialdini's *Influence* (7), Muller's *Essentials of Inventory Management* (6), Baker/Marn/Zawada's *The Price Advantage* (5), Hormozi's *$100M Offers* (5), Simon's *Confessions of the Pricing Man* (5), O'Brien's *Supplier Relationship Management* (4), Voss's *Never Split the Difference* (3), Knaflic's *Storytelling with Data* (3), Meadows's *Thinking in Systems* (3), Lewis's *Moneyball* (3). Where a surprise score was logged — how much the framework changed the answer from what would have happened without it, 1–5 — the average across 63 rated entries sits at **2.97**. Not every consultation is a revelation; most are a framework confirming and sharpening a direction that was already roughly right. The log keeps those too, because a framework that only earns its place on the dramatic cases is not actually being used as doctrine. ## What broke The lookup tool's first version worked well on the queries it was tested with — two or three keywords, exact terms — and badly on the queries it actually receives, which are full sentences. An internal audit found **93% top-3 accuracy on exact short queries and 37% on natural-language ones**, the gap between a demo and production. Two causes, both mechanical. First, no stopword list: short filler words in the query language matched as substrings inside unrelated words — a three-letter function word turned up embedded in an unrelated eight-letter term and pulled in the wrong card. A book with a broad, generic trigger card beat a book with a precise, literal match on the actual topic, purely because the broad card accumulated more substring hits. Second, no handling of word inflection: a plural or declined form of a search term didn't match the singular stem stored in the trigger card, which sinks retrieval hard in any language with rich morphology. The fix was a stopword list, prefix-based matching at a word boundary, and a requirement that part of the match score come from the high-signal fields — triggers, title, mental models — rather than letting a weak match in a low-signal field win on volume alone. A regression harness now runs before any change to the ranking logic and blocks it if exact-match accuracy drops or natural-language accuracy doesn't improve. The lesson generalises past this one tool: a retrieval system tested only on the query shape you'd write by hand will quietly fail on the query shape a real conversation actually produces. ## Acquisition has a filter too Not every book that looks relevant gets added. One recurring signal: ISBN prefix. A `979-8` prefix marks Amazon KDP self-publishing — assigned to anyone who uploads a file, not a signal of editorial vetting. A batch evaluation of candidate titles in one fast-moving technical category found 9 of 11 candidates carried that prefix, and the verdict on one specific title reversed once the prefix was checked against the actual publisher. The second filter is half-life: a book that teaches syntax has a shelf life of months; a book that teaches a method survives the tools changing under it. The library buys for the second kind. ## From brief to playbook A one-page brief is enough to decide whether a book applies. It is not enough to actually carry out its method under pressure — a brief tells you *what* a book argues, not the decision rules and step order you need mid-conversation. Ten books have graduated to a second artefact: a playbook. Not a summary, an executable sequence — when to activate it, what inputs it needs, the procedure with its decision rules spelled out, what trace in the final output proves the method was actually followed, and where it conflicts with another book's advice when two frameworks would point different directions. Promotion to playbook is deliberately lazy: a book earns one only after it has already been used for real, twice, on two separate occasions — not on the strength of how good the book looks on a first read. Writing the executable version before the framework has proven itself in practice would mean encoding untested judgment calls as procedure, which is a more expensive mistake than leaving a good book at the brief stage a little longer than necessary. Delegated work (see **[Twelve Agents, One Memory](/architecture/twelve-agents-one-memory)**) carries this further: a sub-agent handling a domain question gets a line naming the one to three books relevant to its task, and its output is expected to show the book's method applied, not the book's name dropped. The distinction is the same one that killed the citation-frequency floor — *citing* a source and *following* it are different behaviours, and only one of them changes what actually happens next. ## Where this is going Brief coverage sits at 100% of the 123 books — every title that made it into the library has the three artefacts retrieval depends on. What is not yet done: a systematic pass on whether the ISBN-prefix filter has ever produced a false negative — a legitimately good book dismissed on prefix alone — because the filter has only ever been tested for false positives.