The Librarian Agent.
A multi-turn retrieval agent that walks your Cairns tiers on your behalf. L1 first, L2 Chain of Density Card Catalog Layer if needed, L3 only when forced. Your main agent gets the answer, not the rummaging. In the workshop repo today, the entry-point ships as a skill called cairns-query. The full Librarian is what you grow toward.
- A mental model for mediated retrieval one agent in front of your knowledge, every other agent in your fleet calls it. The pattern the production fleet runs on.
- The
cairns-queryskill the entry-point version that walks the L1, then L2 Chain of Density Card Catalog Layer, then L3 cascade. Any agent on your computer can invoke it today. - A graduation path from a one-shot skill to a multi-turn Librarian subagent that can ask follow-up questions to its own search, with per-agent retrieval profiles.
Walk the Librarian with Claude.
Hand the canonical guide and the skill source off to Claude in one paste. It reads both, walks you through the concept, and helps you install and test the entry-point skill against your own vault.
How this fits in the OS.
The Cairns Three Tiers framework, and a Cairns vault on your computer with at least an L1/INDEX.md and one or two waypoint files. Without something for the Librarian to read, there is no Librarian.
The cairns-query skill (the entry-point that ships today), your local Cairns vault, and any retrieval accelerators you already have wired in. Optional later: full-text search, a search-by-meaning index (the technical name is a vector store), or a knowledge graph for relationships over time.
One mediated entry point to your knowledge. Every other agent in your fleet calls the Librarian instead of querying stores directly. Strategy stays consistent, your main agent's working memory stays focused, and the security boundary lives in one place.
What the Librarian actually does.
The Librarian is a retrieval agent that runs on behalf of your main agent. You ask your orchestrator a question. The orchestrator hands the question to the Librarian. The Librarian walks your Cairns tiers, L1 first, L2 Chain of Density Card Catalog Layer (Card Catalog Layer for short) if it has to, L3 only when forced, and hands back just the answer plus citations. Your orchestrator never sees the rummaging.
"Multi-turn" is the load-bearing word. The Librarian can ask follow-up questions to its own search. First pass came back thin? It refines the query and tries again. The first L1 waypoint pointed at a stale L2 Chain of Density Card Catalog Layer card? It goes back, picks a different waypoint, tries a different tier. The whole reason this is an agent and not a search function is that searches are single-shot. A Librarian is allowed to think.
Plain RAG is passive: embed a query, do a cosine-similarity lookup, return the top results. The strategy is hardcoded. The system has no opinion about whether the strategy was right. Agentic retrieval is active: the Librarian picks the strategy per query, runs as many passes as it needs, falls back when confidence is low, and stops as soon as it has the answer.
The point is not that this saves you tokens. The point is that your main agent's working memory stays focused on the task you actually gave it. The Librarian's session is its own. The orchestrator gets the finding, not the search log.
The cascade pattern.
The Librarian always walks the tiers in the same order. The pattern is the contract. Every Cairns build, every Librarian configuration, every retrieval skill inherits this order.
Waypoint check
every queryRead the route map first. Always start at cairns/L1/INDEX.md, then any relevant waypoint files in cairns/L1/personal/. L1 is free, fast, and tells the Librarian which categories exist, what you're working on right now, and which L2 Chain of Density Card Catalog Layer cards or folders to check next.
If L1 answers the question on its own, the Librarian stops here and cites the L1 file. The design target on a healthy vault: most queries resolve at L1 alone. If yours are bouncing past L1 to L2 Chain of Density Card Catalog Layer or L3 on questions L1 should know, the L1 layer is too sparse, not the retrieval too dumb.
Card Catalog Layer scan
when L1 missesSearch the dense-summary cards. If L1 pointed at a topic but didn't carry the detail, the Librarian searches cairns/L2/cards/ and reads the top three to eight cards. Each card is a Chain-of-Density summary of an L3 source plus a pointer back to the raw thing, so the Librarian can read three short cards instead of three long transcripts.
If the cards answer the question, the Librarian cites the L2 Chain of Density Card Catalog Layer card paths and stops. The orchestrator never sees the L3 sources because they weren't needed.
Raw evidence
only when forcedOpen the raw source only when the answer needs it. Exact quotes. Timestamps. Specific names. Anything the dense summary in L2 Chain of Density Card Catalog Layer deliberately compressed away. The Librarian opens the L3 file the L2 Chain of Density Card Catalog Layer card points at, pulls the specific evidence, and cites both the L2 Chain of Density Card Catalog Layer card and the raw L3 path.
L3 is the slowest and most expensive layer. The cascade exists so the Librarian only pays that cost when nothing cheaper will do.
The cascade halts early on purpose. A healthy vault answers a "what's my active project?" question from L1 and never opens L3. If it does, the L1 waypoint is missing or stale. Fix the vault, the Librarian doesn't need fixing.
What ships today: the cairns-query skill.
The entry-point version of the Librarian ships in this workshop repo as a skill, not as a standalone agent. The skill is named cairns-query, and it lives at configs/skills/cairns-query/SKILL.md. It walks the cascade above, returns an answer with citations, and stops. It is the version 4D students use, and it is the foundation an 8D Librarian builds on top of.
What the skill does for you, today, with no extra build:
- Reads
cairns/L1/INDEX.mdfirst on every call, and any L1 waypoint files relevant to your question. - Searches
cairns/L2/cards/only if L1 misses, reading the top three to eight cards by keyword and tag match. - Opens L3 only when forced. Exact quotes, timestamps, evidence the L2 Chain of Density Card Catalog Layer card compressed away.
- Returns answers in a fixed shape. Direct answer, sources used (L1 path, L2 Chain of Density Card Catalog Layer path, L3 path if opened), confidence with one reason.
- Refuses to skip L1. It is not a search bar. It is a cascade.
You invoke it like any other skill. In Claude Code, ask a question and reference the skill by name. The agent reads the skill instructions, walks the cascade on your vault, and reports back. The agent does the cascade for you. You write the L1 waypoints. The skill enforces the order.
The skill needs something to read. Go through the Cairns Three Tiers card first, then use the starter-cairns-packs card to scaffold an L1 with five categories. Five waypoint files is enough to feel the cascade work. Sixteen is the long-run target, but five is enough for the skill to do its job.
What a full Librarian adds.
The skill is the practice version. The full Librarian is the production version, and three things distinguish it from the skill that ships in the box. None of these are bolted onto cairns-query. You build them when your fleet grows past what the skill handles cleanly.
The cairns-query skill
One agent, one vault, single-pass. The cascade runs once. The answer comes back with citations. You read it. Done.
- Same retrieval order, every time
- One model (whichever your agent is running)
- One profile (yours)
- Stops at the first tier that answers
Right answer when you have one agent and one store. Most students live here.
The full Librarian
Multi-turn, multi-profile, model choice. A standalone agent your orchestrator calls. The Librarian can refine its own query mid-search and configure itself per calling agent.
- Multi-turn refinement. The Librarian can ask follow-up questions to its own search if a first pass comes back thin.
- Per-agent retrieval profiles. Different agents in your fleet need different cuts of the same knowledge. The Librarian honors that with one configuration per calling agent.
- Model choice for the retrieval workload. The production reference runs on Gemini, picked specifically for the multi-turn workload it handles best. The Librarian picks the model per task, the same way it picks the strategy.
Right answer when you have three or more agents and two or more stores. Until then, the abstraction costs more than it saves.
The graduation rule. One agent and one store, talk to the store directly through the skill. Three agents and two stores, that is when you spec a Librarian. The skill is not training wheels you abandon. It is the contract your full Librarian inherits. When you build the Librarian, the same cascade order, the same citation format, the same refusal to skip L1 carry forward.
Different agents need different cuts of the same vault. A teaching agent wants concept anchors at L1, module content in the L2 Chain of Density Card Catalog Layer, full lessons at L3. A business agent wants pricing frameworks at L1, case studies in the L2 Chain of Density Card Catalog Layer, meeting transcripts at L3. A wildcard agent wants culture anchors at L1 and broad L2 Chain of Density Card Catalog Layer access for unexpected connections. One Librarian, four profiles, one cascade. Adding a fifth agent doesn't mean re-implementing retrieval. It means writing one more profile.
Why this preserves your orchestrator.
The strongest reason to put the Librarian in front of your knowledge is not cost, and it is not cleanliness of architecture. It is your main agent's working memory, the agent's term for what it can actively hold in mind during a session.
Without a Librarian, your orchestrator does its own retrieval. Every search, every false start, every L3 file it has to open and discard, all of it lands in the orchestrator's working memory and stays there. By the time the orchestrator has the answer it needs, half its memory is taken up by the search log of how it got there. The next instruction you give the orchestrator is competing with that log for attention.
With a Librarian, the search log lives in the Librarian's session. Your orchestrator gets the finding, not the rummaging. The orchestrator's working memory stays clean for the actual task. The Librarian throws its session away when it's done. Next time you ask, the Librarian starts fresh.
A naive pattern has every agent in your fleet querying every store directly. Three agents and two stores means six retrieval paths to maintain, six places strategy drifts, six surfaces where credentials sit. A Librarian pattern collapses that to one retrieval surface: every agent calls the Librarian, the Librarian holds the credentials, the Librarian enforces the cascade. Strategy stays consistent. Cost stays capped. Security lives in one place.
What changes for you.
The skill is the easy part to install. The shift is in how you think about agent memory. Three changes you'll feel:
- You stop letting every agent improvise its retrieval. The cascade order used to be whatever the agent decided in the moment, prompt to prompt. Now there's one policy, in one place, and the rest of your fleet inherits it. You catch yourself writing one skill instead of patching three agents.
- You start thinking in retrieval contracts, not retrieval calls. Each calling agent has a contract with the Librarian: what it asks for, what comes back, what gets cited. The contract becomes the design surface. Once you see retrieval that way, you don't go back.
- You diagnose "the agent missed it" differently. Almost always it is the vault, not the Librarian. The skill jumped to L3 because L1 was empty. The cascade halted on a stale waypoint. The fix is upstream of retrieval, in how the knowledge is tiered, not in the retrieval itself.
This is the moment your knowledge stack stops feeling like four agents racing to the same database and starts feeling like a system with a Librarian out front.
Where to go next.
You understand what the Librarian is and what version of it actually ships today. The natural next moves: