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

Content Model

What Spandrel knowledge graphs are made of — markdown Things addressed by file path, organized via directory hierarchy, connected via frontmatter links, with companion files for design docs and agent instructions

Content Model

The content model defines what a Spandrel knowledge graph is made of. Every graph is a directory tree of markdown files compiled into nodes and edges.

A Thing is a node in the graph. It has a name, description, content, and links to other Things. Things are organized into a hierarchy (the directory tree) and connected across the hierarchy (via links in frontmatter). Some Things become atoms — the canonical, reused units agents compose from — a role they earn through edges and authorship, not a frontmatter field.

The content model covers:

  • Nodes — how Things are represented as files (foo.md or foo/index.md)
  • Atoms — the role a Thing plays when it's canonical and reused; what agents compose from
  • Links — how Things connect to each other via frontmatter declarations
  • Paths — how file paths become graph addresses
  • Companion files — non-node files that travel with nodes (DESIGN.md, SKILL.md, AGENT.md, README.md, CLAUDE.md, AGENTS.md)
  • Reserved prefixes — files and directories starting with _ are excluded from the graph (e.g. _access/, _agents/)