Core Concepts

WarmHub is a knowledge platform for AI agents — purpose-built so that knowledge your agents gain persists, compounds, and stays yours. Think of it as what GitHub did for code, applied to knowledge: versioned, attributed, auditable, and shareable.

Traditional databases store rows. WarmHub stores knowledge about the world — versioned, attributed, and queryable. What sets it apart is that assertions carry confidence, evidence, and attribution — so you can model not just what was recorded, but how strongly it’s held and who holds it. Multiple agents can record different assertions about the same thing, and the system preserves all of them with full provenance. Knowledge compounds across sessions, agents, and teams — each agent builds on what previous agents discovered.

This makes WarmHub ideal for:

• Knowledge that persists — Agents write observations and decisions as structured assertions. Knowledge persists across sessions, so agents don’t start from zero every time.
• Multi-agent coordination — Multiple agents working on the same problem write to a shared repo. Each version is attributed, so you can trace who said what and when.
• Confidence and evidence — Model confidence, evidence, and competing perspectives as first-class data. Assertions from different agents coexist — you can compare, reconcile, or let them evolve independently.
• Auditable repos — Every version of every entity is preserved. You can always ask “what did we know at time T?” or “who changed this and why?”

WarmHub organizes that 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 entity
                └── about → references a shape or shaped 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 a shape or shaped 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 entity. It’s also a thing itself (with its own shape, name, and versions), but it carries an additional untyped about wref linking it to a shape or shaped-thing subject.

wh assertion create --shape Observation --name cave-observation --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": "Observation/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 discovers:

1. Create shapes to define your data types: Location, Player, Observation
2. Add things under those shapes: Location/cave, Player/alice
3. Make assertions about things: an Observation assertion about Location/cave recording that 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.