Why Agent-Native?

WarmHub is designed as agent-native knowledge infrastructure. 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 learned — knowledge compounds across sessions and teams 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 believe at time T?”

Context bootstrapping. The wh prime command and warmhub_repo_describe MCP tool give agents a complete context dump in a single call — shapes, sample data, write contract, and examples tailored to the repo’s actual schema.

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.

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_repo_describe for orientation
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

Agent Workflow Pattern

A typical agent session:

1. Bootstrap — call warmhub_repo_describe or wh prime to understand 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, decisions, or beliefs 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.