Every hierarchy faces the same fork
You are building a structure — a document, a codebase, a knowledge base, a mental model of your domain. You create a level. You place items at that level. And then you hit a decision that will determine whether the structure stays useful or collapses under its own weight: does this item live inside this level, or does it live elsewhere and get pointed to from here?
That is the distinction between containment and reference. Containment means the item is embedded within the parent — it exists as part of the whole, shares the parent's lifecycle, and cannot be accessed independently. Reference means the item exists on its own, in its own location, with its own lifecycle — and the parent merely holds a pointer to it.
This sounds like a technical detail. It is the single most consequential structural decision you make every time you organize anything.
The concept has deep roots in how you think
Before this shows up in software or note-taking tools, it shows up in your body. Cognitive linguist Mark Johnson, working with George Lakoff, identified what they called image schemas — recurring patterns of bodily experience that structure all abstract thought. One of the most fundamental is the containment schema: the experience of things being inside a boundary, outside a boundary, or crossing a boundary. You understood containment before you understood language. You put blocks in a box. You climbed into a room. You felt food go into your body. That IN-OUT logic became the scaffold for concepts like categories, arguments, and logical inclusion (Johnson, 1987; Lakoff, 1987).
Philip Johnson-Laird's mental models theory (1983) adds the other half. When you reason about relationships, you build internal models — simplified representations of how objects relate. Some objects in those models are embedded directly in the scene. Others are tokens that stand for something located elsewhere — what cognitive scientists describe as mental pointers. When you think "the project plan contains the timeline," you are building a containment model. When you think "the project plan references the budget spreadsheet," you are building a pointer model. Different internal structures, different reasoning affordances.
You already do this naturally. The lesson is about doing it deliberately.
Containment: when the part belongs to the whole
Containment means the child item has no independent existence outside its parent. Delete the parent, and the child is gone. Move the parent, and the child moves with it. The child's meaning is inseparable from the context the parent provides.
In software architecture, this maps to composition — the filled diamond in UML class diagrams. A House composes Room objects. Destroy the house, the rooms cease to exist. Eric Evans' Domain-Driven Design (2003) codifies this as the aggregate pattern: value objects are contained within an aggregate root, share its transactional boundary, and cannot be referenced from outside. The aggregate root owns them completely. You do not hold a pointer to a room's wall from some other part of the system — you go through the house.
In document design, containment is the content that lives directly in the artifact. The executive summary is written inside the strategy document. The method section is written inside the research paper. If you delete the paper, the method description goes with it. Contained content makes artifacts self-sufficient — a reader can understand the core argument without clicking a single link.
In personal knowledge management, containment is Notion's page-within-page model — the sub-page that lives inside a parent page and appears in its body. It is the ![[note]] embed syntax in Obsidian, which renders another note's content directly inline. Ahrens' Zettelkasten distinguishes literature notes (contained within the context of a source) from permanent notes (independent objects in the system). The literature note is contained by the reading experience. The permanent note graduates to referenced independence.
The advantage of containment: coherence. Everything the reader needs is right here. No broken links. No context-switching. The artifact tells a complete story.
The cost of containment: rigidity and duplication. If the same content needs to appear in three documents, you now have three copies to maintain. Update one, and the others drift. The 200-page requirements document that nobody reads is a containment failure — everything was embedded, nothing was extracted, and the weight of the whole became unusable.
Reference: when the part has its own life
Reference means the child item exists independently. The parent holds a pointer — a link, an ID, a citation — but does not own the child. Delete the parent, and the child survives. Multiple parents can point to the same child. The child can change without the parent knowing.
In UML, this maps to aggregation — the hollow diamond. A Department aggregates Employee objects. Dissolve the department, and the employees still exist. Evans' DDD enforces this at aggregate boundaries: one aggregate references another aggregate only by its root ID, never by containing it directly. This keeps each aggregate independently deployable, independently consistent.
Ted Nelson, who coined the word "hypertext" in 1963, envisioned reference as the fundamental organizing principle of information. His Project Xanadu proposed transclusion — a mechanism where content from one document appears in another while maintaining a live link to the original. Unlike containment (which copies), transclusion references. Unlike a simple hyperlink (which requires navigation), transclusion renders the referenced content in place. Nelson wrote that "a link is a connection between things which are different, and a transclusion is a connection between things which are the same" (Nelson, 1999). The web gave us links. It mostly failed to give us transclusion. That failure shapes how every knowledge tool works today.
In personal knowledge management, reference is the [[note]] wiki-link in Obsidian — a pointer you click to navigate, but the referenced note stands on its own. It is Notion's linked database view — a window onto data that lives elsewhere, updated in one place and reflected everywhere. In Ahrens' framework, the permanent note is designed to be referenced from many contexts. Its value comes precisely from the fact that it is not contained by any single project or document.
The advantage of reference: modularity. Change the source once, and every reference reflects the update. Share one item across many contexts without duplication. Keep artifacts lean — the project plan is two pages because it links to the detailed specs rather than embedding them.
The cost of reference: fragility and indirection. Links break. References go stale. A document that is nothing but pointers requires the reader to chase six links to understand a single decision. And if the referenced item changes in ways the referencing context did not anticipate, the meaning of the reference shifts without warning.
The real decision: what belongs inside the boundary?
Containment and reference are not alternatives where one is better. They are complementary strategies, and the skill is choosing correctly at each node. Here is the decision framework:
Contain when:
- The item has no meaning outside this context (a method section belongs to its paper)
- The reader must understand this item to grasp the parent (a key conclusion must be stated, not just linked)
- The item's lifecycle is bound to the parent (delete the project, delete its local tasks)
- Independent existence would create dangerous ambiguity (a regulatory clause must be verbatim in the contract, not referenced from a shared library that might change)
Reference when:
- The item is shared across multiple contexts (a company definition used in twelve documents)
- The item changes independently and consumers need the latest version (a pricing table referenced by sales decks, proposals, and the website)
- The item is too large to embed without destroying the parent's readability (a 50-page research report behind a one-sentence summary with a link)
- You want to maintain a single source of truth (one canonical spec, many references)
The master pattern is: contain what the reader must know here, reference what the reader can follow when they need depth. A well-structured artifact is self-sufficient for its primary audience and connected to the broader system for anyone who needs to go deeper.
What this looks like in practice
Consider a team wiki page for a product launch:
- Contained: The launch date, the three key messages, the success metrics, the owner's name. These are the page's reason for existing. Remove any of them, and the page fails its purpose.
- Referenced: The full marketing plan (linked, not embedded — it has its own lifecycle). The customer research (linked — it serves multiple initiatives). The engineering timeline (linked — it updates daily and the launch page should not be the canonical source).
If you contained everything, the page would be thirty pages long, constantly out of date, and nobody would read it. If you referenced everything, the page would be a list of links — a table of contents pretending to be a document, with no standalone value.
The same pattern applies to your personal knowledge system. A permanent note on "second-order effects" should be a standalone, referenced object — it connects to dozens of contexts. But when you write an essay about a specific policy decision, the analysis of that decision's second-order effects is contained in the essay. You might link to your permanent note on the concept, but the specific application lives here.
Containment and reference in AI workflows
The containment-versus-reference distinction maps directly onto how AI systems handle knowledge. Retrieval-Augmented Generation (RAG) is a reference architecture: the model does not contain the knowledge in its weights. Instead, it holds a pointer mechanism (the retriever) that fetches relevant documents from an external corpus at inference time, then passes them as context. The knowledge lives outside the model. The model references it on demand (Lewis et al., 2020).
In-context learning, by contrast, is closer to containment: you place the information directly in the prompt. Few-shot examples, instructions, and background context are embedded in the input. The model processes them as part of its immediate working context. The knowledge is contained within the conversation boundary.
The tradeoffs mirror the structural ones exactly. RAG (reference) scales to millions of documents but introduces retrieval latency and the risk of fetching irrelevant content. In-context containment gives the model perfect access to exactly what you placed in the prompt, but context windows are finite and every token of contained knowledge crowds out space for reasoning.
When you build an AI workflow, you face the same fork at every knowledge node: do you embed this information in the prompt (contain it), or do you put it in a retrievable store and let the model pull it when needed (reference it)? The answer follows the same logic as every other hierarchy: contain what the model must know for this specific task, reference what it can retrieve if and when deeper context matters.
This is not a metaphor. It is the same structural decision, applied to a different substrate.
The deeper pattern
Containment and reference are not features of any particular tool. They are features of hierarchical organization itself. Every time you build a level in a hierarchy — a folder, a chapter, a class, a team, a mental category — you face this fork. You face it when you decide whether to write the definition inline or link to the glossary. You face it when you decide whether a sub-team reports inside a division or operates as a shared service referenced by multiple divisions. You face it when you decide whether a belief is part of your identity or a tool you hold at arm's length.
The failure mode is defaulting. People who always contain build monoliths — bloated, fragile, impossible to update without cascading changes. People who always reference build webs of indirection — lean on the surface, but hollow when you need an answer and every node points somewhere else.
The skill is making the choice consciously at every node: does this belong inside my boundary, or does it belong behind a pointer? The answer changes based on the audience, the lifecycle, the rate of change, and the purpose of the artifact. There is no universal right answer. There is only the question, asked deliberately, at every level of every structure you build.
That deliberation is what separates a hierarchy that works from a hierarchy that collapses.