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 writes — add, revise, and retract operations that append version history.

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 write history. 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 submit --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

Writes

A write is one or more operations submitted to WarmHub. All mutations use the same write pipeline. A request can contain multiple add, revise, and retract operations.

wh commit submit --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}}
]'

A successful write returns:

• Per-operation status — each add, revise, or retract reports success, noop, or failure
• Version updates — successful operations append version history for the affected thing
• Timestamped history — thing history shows when each version was created

How They Fit Together

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

1. Create shapes to define your data types: Location, Player, Belief
2. Add things under those shapes: Location/cave, Player/alice
3. 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)
4. Write related changes together — multiple operations can go in one request
5. Query the current state with thing list, or trace history with thing history

Every entity is versioned. Every write appends thing history. Every assertion knows its subject. Knowledge compounds — each interaction builds on everything that came before, and nothing is lost.