Why Agent-Native?

WarmHub is designed as an agent-native knowledge platform. AI agents can read and write structured knowledge through standard protocols, with built-in attribution, versioning, and context bootstrapping. Every agent builds on what previous agents discovered — knowledge compounds across your work, your team, and your community instead of resetting at the end of each conversation.

Agent-Friendly Properties

MCP-first. WarmHub exposes all operations via the Model Context Protocol, so any MCP-compatible client (Claude, Cursor, custom agents) can discover and call tools automatically.

Structured knowledge. Shapes enforce schema on agent-written data. Agents can’t write malformed records — the write path validates every operation.

Attribution. Every version records the authenticated user’s email as createdByEmail and may also include an optional committer wref (e.g. Agent/claude) identifying the actor on whose behalf the write was made. When multiple agents collaborate on the same repo, you can always trace who wrote what.

Immutable history. Agents can’t silently overwrite data. Every change creates a new version, and old versions are preserved. You can always answer “what did agent X assert at time T?”

Context bootstrapping. Agents orient in two steps. First, wh prime (CLI) or warmhub_capabilities (MCP) return static bootstrap context — concepts, wref syntax, and the command/tool surface. Then warmhub_repo_describe returns a repo-specific dump of shapes, sample data, and the write contract tailored to the repo’s actual schema. See the bootstrap surface map for the CLI/MCP/SDK equivalents.

Batch operations. Agents can submit multiple operations in one request. $N/#N placeholders let agents create entities and reference earlier operations in the same stream. See operation tokens.

Agent Bootstrap Surface Map

Every surface has the same two bootstrap steps — get static orientation, then load the repo’s schema. The tools line up across CLI, MCP, and SDK:

Step	CLI	MCP	SDK
Static orientation — concepts, wref syntax, the command/tool surface	wh prime	warmhub_capabilities	Read these docs; client.diagnostics.capabilities() returns the backend API version, minimum supported SDK, and feature flags — not orientation prose
Repo schema — shapes, sample data, and stats for a specific repo	wh repo describe	warmhub_repo_describe	client.repo.get + client.shape.list + client.repo.getStats

Only warmhub_repo_describe (MCP) also returns the full write contract and generated write examples; the wh repo describe and SDK reads cover schema, shapes, and stats. MCP and SDK names are otherwise near-1:1 — see the SDK and MCP method map.

Integration Paths

MCP Server (recommended)

For AI agents that support the Model Context Protocol:

1. Configure the MCP endpoint in your client
2. Agent discovers the MCP tool catalog automatically
3. Start with warmhub_capabilities for orientation, then warmhub_repo_describe for repo-specific schema and write examples
4. Use warmhub_commit_submit for writes, warmhub_thing_query for reads

See MCP Server for setup and MCP Tools Reference for the full tool catalog.

TypeScript SDK

For custom agents and applications built in TypeScript:

1. Install @warmhub/sdk-ts (react is only needed if you use the React provider)
2. Create a WarmHubClient with your deployment URL
3. Use typed surfaces: client.thing.head(...), client.commit.apply(...)
4. Use OperationBuilder for multi-operation submissions with client-side validation

See SDK Overview for setup and Client Surfaces for the full API.

CLI with —json

For agents with shell access:

1. Install wh CLI
2. Set WARMHUB_REPO environment variable
3. Run wh prime --json for structured context
4. Use wh commands with --json for machine-readable output

export WARMHUB_REPO=myorg/myrepo
wh prime --json              # bootstrap context
wh thing list --json         # read current state
wh commit submit --ops '...' # write data

See Agent Context (wh prime) for how harnesses invoke wh prime, its flags, and its token budget.

Agent Workflow Pattern

A typical agent session:

1. Bootstrap — call warmhub_capabilities (MCP) or wh prime (CLI) for static orientation, then warmhub_repo_describe to load the repo’s schema, existing data, and write contract
2. Read — use warmhub_thing_head for broad orientation, warmhub_thing_query for targeted lookups
3. Write — commit observations and decisions via warmhub_commit_submit (opinion-bearing assertions must be binary propositions)
4. Iterate — read updated state, make new assertions, revise existing ones

The describe tool dynamically generates write examples based on the repo’s current shapes, so agents get correct field names and types without guessing.

For guidance on what to model and how — when to use assertions vs things, shape design, naming conventions, and common patterns — see Modeling Overview. For the underlying data model, see Core Concepts.