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 commit pipeline validates everything.

Attribution. Every commit records an author field. 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, commit contract, and write examples tailored to the repo’s actual schema.

Batch operations. Agents can commit multiple operations atomically. The $N/#N token system lets agents create entities and reference them in the same commit.

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_apply 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 CommitBuilder for multi-operation commits 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 head --json         # read current state
wh commit create --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_apply
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 pitfalls — see Principles & Patterns. For the underlying data model, see Core Concepts.