Stratum MCP

Stratum

State machine dispatch server for AI agent workflows.

Your agent proposes the step. Stratum decides whether it actually finished.

Stratum gives AI coding agents (Claude Code, Codex, etc.) a formal execution model. Instead of improvising a plan and retrying blindly, the agent writes a typed spec, the server tracks state, enforces postconditions, and returns structured failure context on retry. Every step produces an auditable trace record.

Where it sits. Stratum is the execution kernel, one layer below the thing most people run day to day. Compose drives the product lifecycle (design, blueprint, plan, review gates) and calls Stratum to execute each step. Reach for Stratum directly when you want the state machine and the postconditions without a lifecycle on top of them.

The founding intent behind this machinery is recorded in docs/VISION.md: a spec language that keeps LLMs on rails invisibly, so the same conversation yields stronger results than freeform execution.

One shipped component:

• ts/ — the TypeScript engine (@smartmemory/stratum): IR validation (version: 1 specs), flow execution with ensure postconditions, MCP server for Claude Code, query/gate/guard CLI, background flows and background agent runs. Published to npm as @smartmemory/stratum (bins: stratum, stratum-mcp) and listed in the MCP registry as ai.smartmemory/stratum-mcp.

Engine status (2026-07-18, STRAT-PY-RETIRE): the TS engine is the ONLY engine. The Python library (stratum-py) and Python MCP server (stratum-mcp) are retired. Their source is archived on the python-legacy branch, and PyPI packages are frozen at their final releases. The engine executes version: 1 specs exclusively. Legacy v0.x specs are rejected by validate and classified (report-only) by stratum migrate --check. The authoritative v1 shape is the Zod IR schema in ts/src/ir/ plus stratum validate output.

Governed workflows as auditable flows — on any agent, not just one vendor. Unlike a single-vendor in-context orchestrator, Stratum runs as an MCP server and a library under Claude Code, Codex, or any MCP host; enforces typed contracts and ensure postconditions on every flow execution; stops at real human gates; dispatches Claude and Codex agents in one flow (so an independent reviewer can be a different model from the implementer); and persists flow state across sessions. Where you want raw in-context fan-out, reach for an in-host workflow runtime; where you want the run governed, portable, and auditable, that's a Stratum workflow.

Table of Contents

• Installation
• Quick Start
• Core Concepts
• YAML Spec Reference
• MCP Tools API
• Step Types
• Ensures (Postconditions)
• Contracts and Output Validation
• Gates (Human-in-the-Loop)
• Flow Composition
• Routing
• Iterations
• Checkpoints
• Recovery and Retry Logic
• Workflows
• Task Compiler
• Skills
• CLI Reference
• Configuration
• Python Library (Track 1)
• Examples
• Development
• License

Installation

Install from npm (Node >= 22):

npm install -g @smartmemory/stratum    # provides `stratum` (CLI) and `stratum-mcp` (MCP server)

Or run from a checkout for development:

git clone https://github.com/smartmemory/stratum
cd stratum/ts && npm install    # or pnpm install

Requires node >= 22 (erasable-syntax type stripping; node >= 24 needs no flags — the CLI bootstrap gates --experimental-transform-types automatically).

MCP Server (for Claude Code)

Register the server in your project's .mcp.json. From the npm package:

{
  "mcpServers": {
    "stratum": {
      "command": "npx",
      "args": ["-y", "-p", "@smartmemory/stratum", "stratum-mcp"]
    }
  }
}

From a checkout:

{
  "mcpServers": {
    "stratum": {
      "command": "node",
      "args": ["/absolute/path/to/stratum/ts/src/mcp/bin.mjs"]
    }
  }
}

Restart Claude Code to activate. Optionally append the Stratum execution model block to your CLAUDE.md.

CLI

stratum help                    # validate | migrate | query | gate | guard | watch  (npm install)
node ts/src/cli/bin.mjs help    # same, from a checkout

From a checkout, a thin wrapper script (e.g. ~/bin/stratum-ts) pointing at ts/src/cli/bin.mjs avoids a PATH collision with the installed stratum bin.

Quick Start

When Claude Code has Stratum installed, it uses it automatically for non-trivial tasks:

1. Claude writes a .stratum.yaml spec internally (never shown to you)
2. Calls stratum_plan to validate the spec and get the first step
3. Executes each step using its own tools (reading files, writing code, running tests)
4. Calls stratum_step_done after each step -- the server checks postconditions
5. If a postcondition fails, Claude gets back the specific violation and retries
6. Calls stratum_audit at the end for a full execution trace

You see plain English narration throughout. The spec, state management, and postcondition enforcement happen behind the scenes.

Core Concepts

Specification vs Flow

A specification is the authored, version-controlled .stratum.yaml document. It declares contracts and one or more flows. The flows.entry field selects the flow that starts a run.

A flow is an executable directed acyclic graph of steps. Running the entry flow creates a persisted run with a runId. The v0.x top-level workflow: registration block and stratum_list_workflows were retired with the Python server.

Flows

A flow declares typed input fields, a typed output, optional limits, and steps. References and after lists form data and ordering edges. Gate routing and on_fail add explicit routing edges.

Steps

A step has an id, optional after dependencies, an optional when condition, and exactly one construct: do, set, gate, fanout, or run.

Tasks

A do step is an agent-dispatched task. The task text is declared inline, and ${...} references inject flow input or prior step output values. The v0.x functions: registry and function: steps have no place in a v1 document.

Contracts

Contracts define named output shapes. A do or set step declares its output contract with out. A flow declares both the step-output reference that supplies its result and the contract used to validate that result.

Ensures

Ensures are structured postconditions on do, set, and fanout stage results. V1 supports expression, file existence, file content, and judged predicates.

Retries

A do or fanout step can set the positive integer attempts limit. The default is two attempts. Contract failures, ensure failures, task failures, and exhausted iterations use the same failure path. A deterministic set failure terminates the flow without retrying.

Gates

Gate steps pause execution for an external approve, revise, or kill decision. Approve and kill routes may name a later step or use null. A revise route may name a strict ancestor and requires a flow-level max_rounds limit.

YAML Spec Reference

The Zod IR schema in ts/src/ir/ and the errors produced by stratum validate are authoritative. The root is strict and has exactly three fields: version, contracts, and flows. Unknown fields are rejected.

Minimal Example

version: 1
contracts:
  SentimentResult:
    label: string
    confidence: number
flows:
  entry: classify
  classify:
    input:
      text: string
    output:
      from: "${classify_text.output}"
      contract: SentimentResult
    steps:
      - id: classify_text
        do: "Classify the sentiment of ${input.text}"
        agent: claude
        out: SentimentResult
        ensure:
          - expr: "result.label != ''"
          - expr: "result.confidence > 0.7"
        attempts: 2

Full Example with a Gate

version: 1
contracts:
  WorkOutput:
    result: string
    quality_score: number
flows:
  entry: reviewed_work
  reviewed_work:
    input:
      text: string
    output:
      from: "${work.output}"
      contract: WorkOutput
    max_rounds: 3
    steps:
      - id: work
        do: "Produce the deliverable requested in ${input.text}"
        agent: codex
        out: WorkOutput
        ensure:
          - expr: "result.quality_score >= 0.8"
        attempts: 3
      - id: review
        after: [work]
        gate:
          on_approve: null
          on_revise: work
          on_kill: null
          max_rounds: 2

Full Field Reference

version (required)

The only accepted value is the number 1. Quoted strings such as "1" and all v0.x values are rejected.

contracts (required)

Each contract maps field names to type strings. Objects are strict at runtime, so undeclared output fields are rejected.

Named contract references use an initial capital letter. Recursive contract references and unknown contract names are rejected.