Patterns & Recipes

This page collects modeling patterns that work well in practice. Each pattern builds on the core primitives — shapes, things, assertions, and wrefs.

Agent Memory

An agent writes observations as assertions about entities it encounters:

1. Define a Location shape (or whatever your domain entities are)
2. Define an Observation or Belief shape with fields like confidence, source, evidence
3. The agent adds things as it discovers entities
4. The agent creates assertions about those things as it learns
5. Other agents (or humans) query those assertions to build on that knowledge

# Agent discovers a new entity
wh commit submit --add cave --shape Location --data '{"x": 3, "y": 7}' -m "Discovered cave"

# Agent records what it observed
wh assertion create --shape Observation --about Location/cave \
  --data '{"safe": true, "confidence": 0.8, "source": "agent-1"}' -m "Initial observation"

Knowledge compounds — each session builds on the previous one. The agent doesn’t start from zero because its prior assertions persist.

Multi-Agent Collaboration

Multiple agents write to the same repo. Each commit is attributed, so you can trace who said what:

• Agent A and Agent B can both assert about the same thing
• Their assertions coexist — WarmHub doesn’t force consensus
• A downstream process can compare, reconcile, or aggregate their views

# Agent 1's assessment
wh assertion create --shape Thesis --about Company/acme \
  --data '{"outlook": "bullish", "confidence": 0.7}' -m "Agent 1 thesis"

# Agent 2's competing assessment
wh assertion create --shape Thesis --about Company/acme \
  --data '{"outlook": "bearish", "confidence": 0.6}' -m "Agent 2 thesis"

# Both coexist — query to compare
wh thing about Company/acme --shape Thesis

This pattern works because assertions are attributed and non-exclusive. There’s no conflict — just different perspectives.

Evolving Understanding

As knowledge changes, revise assertions rather than retracting and recreating:

• revise updates the assertion’s data while preserving its identity and history
• The about reference stays the same (it’s immutable)
• You can query the full version history to see how understanding evolved

# Initial belief (explicit name so we can revise it later)
wh assertion create --shape Belief --name cave-safe --about Location/cave \
  --data '{"safe": true, "confidence": 0.8}' -m "First visit"

# Confidence changes after new evidence
wh assertion revise Belief/cave-safe --data '{"safe": false, "confidence": 0.3}' -m "Found hazard"

Only retract when an assertion is truly no longer valid — not just outdated. Revision preserves the full belief trajectory.

Opinions as Separate Assertions

When modeling subjective logic opinions (b, d, u, α) — belief, disbelief, uncertainty, and base rate (serialized as the a field in JSON) — keep opinion metadata separate from the data being asserted. These values describe trust in an assertion, not properties of the thing being described.

Opinions require binary propositions

A subjective-logic opinion (b, d, u, α) is a binomial opinion — it models belief over a two-outcome frame. The assertion it is attached to must be a binary proposition: a statement that is either true or false. Attaching an opinion to an open-ended claim (e.g. “how tall is Greg?”) produces numbers that satisfy b+d+u=1 but are semantically meaningless. Phrase the underlying claim as a binary proposition first (e.g. “Greg is at least 5’4"").

Don’t do this — mixing finding data with opinion metadata:

{
  "shape": "DocFinding",
  "data": {
    "severity": "high",
    "category": "security",
    "b": 0.8,
    "d": 0.1,
    "u": 0.1
  }
}

Do this — a finding thing and a separate opinion assertion about it, in one write request:

wh commit submit --ops '[
  {"operation": "add", "kind": "thing", "name": "DocFinding/finding-$1",
   "data": {"severity": "high", "category": "security"}},
  {"operation": "add", "kind": "assertion", "name": "Opinion/finding-opinion-$2",
   "about": "DocFinding/finding-#1",
   "data": {"b": 0.8, "d": 0.1, "u": 0.1, "source": "scanner-agent"}}
]' -m "Security finding with scanner confidence"

Why separate?

• The finding’s severity is a fact — it doesn’t vary by who observed it
• The opinion (b: 0.8) is the scanner agent’s confidence in that finding — another agent might disagree
• Multiple agents can hold different opinions about the same finding
• You can query all opinions about a finding and fuse them without touching the finding data

This separation follows the same principle as things vs assertions: data about the world goes in things; beliefs about that data go in assertions.

If you want WarmHub to consolidate opinions across sources and weight them by track record, install Veritas — its Certainty, Support, Opposition, and Consensus shapes implement this pattern directly. Veritas’s installed shapes use the long-form field names belief, disbelief, uncertainty, and alpha. The (b, d, u, α) notation in this section is the mathematical form; user-defined opinion shapes (like the DocFinding/Opinion example above) typically serialize those as the short JSON keys b, d, u, and a. Pick the field-name convention that matches the shape you’re writing against.

Under-Grouping

Group related operations

Five separate write requests for five related changes means five separate coordination points. Group related operations in one request when later operations naturally depend on earlier ones, and handle partial success: each operation reports its own status and a later failure does not roll back earlier successes. A request can still fail before any per-operation results are returned (for example, auth or malformed input), so handle both per-op result rows and request-level errors. See Atomicity.

wh commit submit --ops '[
  {"operation": "add", "kind": "thing", "name": "Company/acme", "data": {"industry": "fintech"}},
  {"operation": "add", "kind": "assertion", "name": "Thesis/acme-growth", "about": "Company/acme", "data": {"outlook": "bullish"}}
]' -m "Add company with initial thesis"