Cairns: three tiers to five levels.
The original Cairns three-tier model is still the foundation. Summer Camp names those tiers Levels 1 through 3 and adds vectors and a graph store as Levels 4 and 5. This guide maps the two models and pins the Week 2 exit floor.
- A working mental model for how agent memory should be organized, and why one big context window isn't the answer.
- A four-step cascading retrieval pattern (L1 → L2 Chain of Density Card Catalog Layer → L3 → answer) every Cairns build follows.
- A diagnostic frame for "the agent forgot X", almost always a mis-tiering problem, not a missing-data problem.
Apply this to your knowledge.
Hand the guide off to Claude and have it walk you through tiering your own files. Hits different when it's about your actual life.
How this fits in the OS.
A folder, vault, or repo where raw sources and generated cards can safely live.
L1 waypoints, L2 Chain of Density Card Catalog Layer (Card Catalog Layer for short) summary cards, L3 raw evidence, and human approval loops.
Source-aware answers, durable memory, knowledge workflows, and later librarian agents.
Summer Camp mapping: three tiers, now five levels.
If you learned Cairns in the AgentOS workshop, your memory is right. The original three tiers still form the foundation. Summer Camp names them Levels 1 through 3 and adds two production accelerators as Levels 4 and 5.
| Workshop model | Current Camp level | What you build |
|---|---|---|
| L1 waypoints | Level 1: curated library plus routing index | Readable repo files plus knowledge-index.md |
| L2 card catalog | Level 2: card catalog | Fact blocks tagged observed or inferred, confidence, shelf life, and source |
| L3 raw evidence | Level 3: complete-information layer | Raw originals in your private vault, reached through custody pointers and never stored in git |
| Production search accelerator | Level 4: vectors | Search by meaning across a large library, deferred in Week 2 |
| Production relationship accelerator | Level 5: graph store | A map of how people, facts, and events connect, deferred in Week 2 |
Levels 1 through 3 are standing and real. Levels 4 and 5 are deferred on purpose. Start with the context repo, build the Three-Part Memory System, and use the receipts to prove each level. The accelerators only pay off after the library is large enough to need them.
The shape of the problem.
Every tier of Cairns increases in volume and decreases in curation. At the top: a small handful of the most important things, always loaded. At the bottom: the full raw record, never deleted. The middle layer is the bridge, short summaries of every source, with pointers to where the full thing lives.
The reason this works: most questions don't need the full content of anything. They need the agent to know where to look, what's there, and what's worth fetching. Three tiers mean the agent can stop expensive lookups as soon as the cheap layers resolve the question.
Agents read top-down. They start at L1 waypoints, drop to L2 Chain of Density Card Catalog Layer cards only if needed, and pull L3 raw only for verification. The cascading flow below follows this order, because that's what the agent actually does at runtime.
Humans build bottom-up. You already have the raw stuff (L3). You summarize it into cards (L2 Chain of Density Card Catalog Layer). The most important things rise to waypoints (L1). When you're building your own Cairns, you'll feel the bottom-up direction even though the card walks through it top-down.
The full production Cairns is not what you install today. What follows is the architecture. The student version uses local markdown files and skills. The production version adds automated ingestion, lookup by meaning, graph-style connections, and a Librarian Agent that orchestrates everything. Same shape, different scale. And critically, the agent does most of the work for you. You approve. You don't write all this by hand.
The three tiers.
The always-on route map
What it is. A small, pre-curated route map of high-signal waypoints across your life and work. Always loaded into the agent's context at session start. The first stop for any query.
L1 is not where you summarize every source. L1 tells the agent:
- What matters right now
- Which categories exist
- Which L2 Chain of Density Card Catalog Layer cards or folders are worth checking
- Which decisions, constraints, people, and projects should shape the answer
- What must stay human-approved because it changes the agent's standing memory
The 16 categories (proposed, not yet locked)
| # | Category | Example contents |
|---|---|---|
| 1 | Work, Builds | Active build threads (Cairns, agent-native-os) |
| 2 | Work, Business | Company ops, finance, legal, infrastructure |
| 3 | Work, Curriculum | Foundations 2.0, Build Lab, future cohort prep |
| 4 | Work, Team | Team members, contractors, future hires |
| 5 | People, Inner Circle | Family, close friends, key network |
| 6 | People, Network | Mentors, collaborators, students, vendors |
| 7 | Family, Spouse | Marriage, anniversaries, plans, decisions |
| 8 | Family, Kids | Schools, activities, milestones, healthcare |
| 9 | Personal, Health | Allergies, meals, fitness, providers |
| 10 | Personal, Finances | Personal accounts, investments |
| 11 | Personal, Tools and Setup | Hardware, software, dotfiles, machine state |
| 12 | Personal, Interests | Music, photography, woodworking, etc. |
| 13 | Personal, Self-Development | Reading, learning goals, journaling themes |
| 14 | Decisions in Flight | Active decisions not yet made (under 24h fresh) |
| 15 | Goals and Commitments | What you said you'd do, public and private |
| 16 | Brand and Voice | Voice rules, conventions (under 90d fresh) |
How to keep L1 useful
A few simple practices keep your L1 from turning into a bloated document the agent has to wade through every session:
- Keep entries short, one to two sentences each. Long entries crowd the agent's working memory. If you need more space for something, that detail belongs in the L2 Chain of Density Card Catalog Layer, not here.
- Date every entry. When something was true matters. Without dates, the agent can't tell what's current and what's months old.
- Never overwrite, add a new entry below. If your priority changes, log the new one without deleting the old. You keep the trail, and your agent can see how your thinking has evolved.
- Always point at the source. Even a short note like "(see L2 Chain of Density Card Catalog Layer card: workshop-priorities)" tells the agent exactly where to dig if it needs more detail.
Different categories of L1 need different update rhythms. A "decisions in flight" file goes stale in a day, your active decisions look different tomorrow than today. A "brand voice" file can sit for months, your brand voice doesn't change overnight. Update each category at the pace it actually drifts.
What L1 looks like in practice
Say you're a small business owner six weeks out from a product launch. One waypoint in your L1 might just say:
That's it. That's a waypoint. The agent doesn't have to scan your whole project folder to know what you're working on or where you are in it. One short sentence frames everything that follows, and the pointer tells the agent where to go if it needs more.
You don't sit there writing L1 entries by hand. At the end of a work block, the /cairns-dream skill scans what changed in your conversation and your files, then proposes what should be pinned to L1, updated, or merged. You read the proposal, hit approve or skip on each one. Nothing ever auto-writes without your sign-off.
The Card Catalog Layer
What it is. A searchable index of every meaningful source in your knowledge. One L2 Chain of Density Card Catalog Layer card per L3 source. Each card is a tight summary of the source plus tags, dates, who's mentioned, and a link back to the raw thing in L3.
Think of an actual library card catalog. Each card tells you what exists, where it lives, what it's about, and how to get the full thing. Your agent uses L2 Chain of Density Card Catalog Layer to figure out which sources are worth pulling fully, without having to load everything into memory.
What goes in. One card per source. Every transcript, every important Slack thread, every paper, every meeting that mattered, every article worth keeping. The card includes simple structured info: where the source lives, when it happened, who's in it, what topics it covers, and tags that help the agent find it later.
What makes a good card
The first draft of a summary is almost always too vague. The technique that produces dense, useful cards is called Chain of Density: write a draft, then rewrite the same length asking "what important details did I miss?" Repeat a few times. The result is a short card that still preserves the source's real signal. The full technique walkthrough lives at guides/cairns/05-card-catalog-chain-of-density.md.
You don't run it by hand. Your agent does it for you. Run /cairns-ingest on a new source. The skill runs the loop and proposes the final card. You read it, approve or edit, save.
Where it lives. Markdown files in your repo, viewable in Obsidian. Andrej Karpathy calls a similar pattern "the wiki." In Cairns, the L2 Chain of Density Card Catalog Layer is the bridge between your always-on memory at the top and your raw evidence at the bottom.
The raw data
What it is. The complete, unprocessed source material. Every video transcript, PDF, Slack export, meeting note, email, voice memo, article, or screenshot. Never edited by an AI. Always backed up. This is the source of truth your agent can always verify against.
What goes in. Live session transcripts. Your Slack archive. Curriculum modules. Voice and brand docs. Meeting recordings. YouTube transcripts. Voice memos.
Where it lives. On private storage such as a backup drive or network-attached storage (NAS), never in git. The repo stores sanitized custody pointers and approved context, not the raw originals. At production scale, the agent can split approved sources into searchable pieces, index them by meaning, and keep a version history. You do not hand-organize the raw archive.
How an agent uses all three.
The cascading lookup is the whole point. The agent doesn't run an expensive deep-search for every question. It only does the heavy work when the cheap layers don't already have the answer.
A search-by-meaning index alone (the technical name is vector store: a database that finds content by meaning, not just exact words) can find semantically similar content. It can't reconstruct a story over time. Imagine asking "what shoes does this person wear?" against a year of voice memos where the answer drifts: Nike → Adidas → barefoot. A search-by-meaning lookup returns any of them with no temporal sense. Add a knowledge graph (a layer that tracks how things relate over time, like Nike → superseded → Adidas → superseded → barefoot) and you get the actual arc. Add the L2 Chain of Density Card Catalog Layer with breadcrumbs back to L3 and the agent can verify against the original transcript. The three layers solve what any single one can't: frame the query (L1), scan for relevance (L2 Chain of Density Card Catalog Layer), pull the source-of-truth (L3).
What this looks like at scale. Snapshot of the team's production fleet as of Apr 24, 2026:
At full scale, Cairns runs a layered stack: search-by-meaning indexes on your own machine (Nomic embeddings on Ollama, no per-call charge), stored in a meaning-search database (Supabase with pgvector), plus a graph database (Neo4j) tracking how items connect to each other over time. The L1 you start with on day one is plain markdown files in Obsidian; that scales further than you'd think before the bigger machinery becomes necessary.
How new things get added back in.
The three tiers above describe how the agent finds things. What's just as important, and easy to overlook, is how new things get added back in. Every conversation you have with the agent produces new insights worth keeping. The trick is making sure those insights actually land in your knowledge base so future conversations are smarter than this one.
"I thought I had to reach for fancy retrieval setups, but the LLM has been pretty good about auto-maintaining index files and brief summaries of all the documents and it reads all the important related data fairly easily at this ~small scale. Often, I end up filing the outputs back into the wiki to enhance it for further queries. So my own explorations and queries always 'add up' in the knowledge base."
That's the loop. Each question the agent answers produces an answer that becomes a new L2 Chain of Density Card Catalog Layer card (or a new L3 source) for the next question. Without this loop, exploration is throwaway. You ask, you get the answer, you move on. With it, every conversation makes the system smarter the next time you use it.
Three sides to Cairns, not two:
- Read side: when you ask the agent something, it follows the cascade above to find the answer.
- Write side: when the agent learns something useful from your conversation, it files it back in. A new L2 Chain of Density Card Catalog Layer card from a session that mattered. A new L1 pin from a decision you just made. The system gets smarter every time you use it.
- Consolidate side: at the end of a day or week, the
/cairns-dreamskill runs a "sleep pass." It scans what changed, proposes what should be promoted, merged, or distilled. It never auto-writes anything. Every proposal waits for you to approve, skip, or edit. You stay in the loop; the agent does the proposing.
The sleep metaphor matters. Biological sleep is what moves your short-term experience into long-term memory. /cairns-dream does the same job for your agent's knowledge, it takes the raw activity of a session and turns it into structured layers. Run it at the end of a work block, not in the middle.
HOT, WARM, COLD: the agent's view.
The same three tiers from the agent's perspective. HOT/WARM/COLD names where each tier sits in the agent's working memory, not the storage layer.
| Tier | Cairns layer | What it means |
|---|---|---|
| HOT | L1 Cairns | Always in the model's context. No fetch needed. |
| WARM | L2 Chain of Density Card Catalog Layer | Known to exist by name. Deliberately fetched on demand. |
| COLD | L3 Raw Data | Not known by name. Searched, embedded, or graph-traversed to discover. |
Most agent failures are tier-mismatch, not missing data. Putting things in HOT that should be WARM crowds the agent's working memory. Putting things in WARM that should be HOT means the agent forgets to look them up. Putting things in COLD that should be WARM forces an expensive search every time for something the agent could just open directly. The discipline of choosing the right tier is worth more than the storage itself.
What changes for you.
The architecture is the easy part. The shift is in how you think about what you're saving and where it goes. Three changes you'll feel:
- You stop dumping everything into one big context. Each session no longer feels like "remind Claude of everything." The agent already knows the things you've tiered well.
- You start asking "which tier does this belong in?" before you write. A new decision is L1. A meeting transcript is L3 with an L2 Chain of Density Card Catalog Layer card. A brand voice rule is L1 in long form. The choice happens at capture time, not search time.
- You diagnose "the agent forgot X" differently. Almost always it's tiering, not missing data. The fix isn't to write more, it's to move what you already wrote to a different tier.
The 3-tier discipline forces a decision for every piece of knowledge: which tier does it belong in? That decision is more valuable than the storage itself.
Where to go next.
You now understand the data shape. The natural next moves: