Core Concepts

WarmHub organizes knowledge into a hierarchy of concepts. Understanding these building blocks is essential to working with the platform.

Before diving into the hierarchy, a few key terms used throughout WarmHub:

wh — the WarmHub CLI command
wref — a WarmHub reference, the human-readable address for any entity (e.g., Location/cave). See Wrefs for the full reference.

The Hierarchy

Organization
 └── Repository
      └── Things (all entities share one table)
           ├── kind: shape — schema definition
           ├── kind: thing — named entity with data
           └── kind: assertion — claim about another thing
                └── about → references any thing

All changes to entities happen through Commits — atomic batches of add/revise operations.

Organization

An org is the top-level namespace. It groups related repositories under a single identity.

wh org create acme --display-name "Acme Corp"

Repository

A repo lives inside an org and contains all your data — shapes, things, assertions, and commits. It’s the primary container for data isolation.

wh repo create acme/world -d "Game world knowledge base"

Shape

A shape defines the data structure (schema) for things and assertions. Think of it as a type definition. Shapes specify what fields an entity’s data can contain and what types those fields are.

wh shape create Location --fields '{"x": "number", "y": "number", "label": "string"}'

Field types include string, number, boolean, and wref (a reference to another thing). Shapes are versioned — you can revise a shape’s fields and existing data remains tied to the version it was validated against.

Thing

A thing is a named, versioned entity within a repo. Every thing belongs to a shape. Things are the core data objects — they represent the entities in your domain.

wh commit create --add cave --shape Location --data '{"x": 3, "y": 7, "label": "Dark Cave"}'

Things are identified by their wref: Shape/name. For example, Location/cave refers to the thing named cave under the Location shape.

Assertion

An assertion is a claim about another thing. It’s also a thing itself (with its own shape, name, and versions), but it carries an additional about reference linking it to its subject.

wh assertion create --shape Belief --about Location/cave --data '{"confidence": 0.8, "source": "agent-1"}'

Key properties of assertions:

The about target is immutable — set at creation and cannot be changed
about can point to things in the same repo (local wrefs) or other repos (canonical wrefs)
Multiple assertions can be about the same thing — this is how you model multiple perspectives or attributes

Commit

A commit is an atomic batch of operations. All mutations in WarmHub go through commits. A commit can contain multiple add and revise operations that succeed or fail together.

wh commit create --ops '[
  {"operation": "add", "kind": "thing", "name": "Location/cave", "data": {"x": 3, "y": 7}},
  {"operation": "add", "kind": "assertion", "name": "Belief/cave-safe", "about": "Location/cave", "data": {"safe": true}}
]'

Every commit records:

Author — who made the change
Message — optional description of the change
Operations — the list of adds and revises
Commit ID — stable hash identifier for the commit
Timestamp — when the commit was created

How They Fit Together

Here’s a concrete example — modeling a game world where an agent explores and records what it learns:

Create shapes to define your data types: Location, Player, Belief
Add things under those shapes: Location/cave, Player/alice
Make assertions about things: a Belief assertion about Location/cave recording that the agent believes the cave is safe (with a confidence of 0.8)
Commit all changes atomically — each commit gets a stable hash identifier
Query the current state with thing head, or trace history with thing history

Every entity is versioned. Every change is a commit. Every assertion knows its subject. Knowledge compounds — each interaction builds on everything that came before, and nothing is lost.