SpandrelA framework that turns markdown file trees into governed knowledge graphs — philosophy, spec, and reference implementation

Atoms

Atom is a role a Thing plays — canonical, reused, many incoming edges, stable schema, single source of truth for a concept. Not a frontmatter axis; a role observable from edges and authorship. Atoms are what agents compose from when they walk the graph.

Atoms

Every node in a Spandrel graph is a Thing — the primitive type. Atom is the name for a Thing that plays the canonical-and-reused role: the unit agents compose from when they walk the graph to assemble context.

Atom is not a new axis in the content model. There is no atom: true frontmatter field. Atom-ness is a role, observable from edges and authorship — not declared in markdown. The existing node axes (kind: node vs document, navigable) are unchanged.

What makes a Thing an atom

  • Many incoming edges. Other Things reference it; it's load-bearing across the graph. Backlinks make this visible — see linking.
  • A stable schema. Its shape is consistent with its siblings, so agents can rely on what they'll find.
  • A canonical identity. It is the single source of truth for its concept. When two atoms conflict, the agent has to adjudicate — and the quality of that adjudication depends on how clearly each atom states its position.

Personas, jobs-to-be-done, value props, design tokens, customer segments, strategic bets, success metrics, decisions, runbooks — these are atoms. They're the canonical, reused units of composition.

Non-atom Things have few incoming edges and looser shape: transcripts, raw exports, working notes, drafts. They contribute to the graph but aren't load-bearing for composition — and are often kind: document, navigable: false.

Graduating to atom status

Information becomes atomic knowledge when it graduates into a Thing that serves as a composition primitive. This is an authorship discipline: identifying which concepts are stable and reused enough to warrant canonical-source status, then maintaining each as the single source for its concept.

Stability is the result of that discipline, not an automatic property. Atoms are maintained — atom hygiene is ongoing work, performed by humans and increasingly by agents operating against the graph. The graph is a living substrate, not a static read-only artifact.