kumiho-construct 2026.5.11

How Construct fits together

Construct is open source. The persistent graph memory it depends on — Kumiho — is a managed service with open SDKs and an Enterprise self-host option. Three layers, plain language:

LLM inference is bring-your-own-provider. We don't proxy or mark up tokens. You point Construct at Anthropic, OpenAI, OpenRouter, Ollama, GLM, or any of 14+ providers, and your keys stay yours.

Operator (the orchestration layer) needs a provider for its own LLM calls — supervisor decompose, map-reduce reduce, refinement critic, group-chat moderate. It defaults to an API key and also supports OAuth, configured under [operator].

Agents that Operator spawns behave differently. Each agent step invokes the Claude Code or Codex CLI as a subprocess — prompt piped over stdin to avoid ARG_MAX and shell-encoding issues — and the CLI's existing OAuth handles auth. Your Claude Pro / Codex CLI subscription becomes the spawned-agent runtime: no per-call API spend on the spawned agents themselves. Direct API keys still apply to one-shot construct agent calls and channel-routed conversations.

Construct talks to Kumiho over HTTP via [kumiho].api_url in your config. Without a reachable Kumiho endpoint, Construct degrades to stateless single-agent operation — useful for demos and CI, but the cross-session memory, provenance edges, audit chain, and trust scoring all live in the graph. Pricing and self-host: kumiho.io/pricing.

Upstream. Construct's core Rust runtime is a fork of ZeroClaw. The agent loop, provider/channel/tool architecture, hardware peripheral layer, and CLI scaffolding trace back to that upstream; full attribution in NOTICE and the consolidated overview at docs/upstream/zeroclaw-attribution.md. "ZeroClaw" and the ZeroClaw logo are trademarks of ZeroClaw Labs; Construct is not affiliated with, endorsed by, or sponsored by ZeroClaw Labs.

What is Construct?

Construct is a Rust-native AI agent runtime with persistent cognitive memory, multi-agent orchestration, and a shared skill/template marketplace. Every agent session, plan, skill, and trust score lives in a graph — if it happened, it's queryable. Built on Kumiho's graph-native memory system, Construct treats memory not as a feature but as the substrate every agent wakes up in.

At the core: a Rust gateway (Axum) serves a React/TypeScript Web Dashboard, a Python Operator drives multi-agent orchestration, and Kumiho (graph-native, Neo4j-backed) holds all persistent state. Define declarative YAML workflows, watch agents execute them in real time via a DAG-based live view, trace every tool call and output, and see trust scores evolve across runs — all from a browser.

No hidden state. No forgotten runs. The only thing the system asks of you is that you notice.

Free tier, Studio trial, and referrals

Kumiho is the persistent backend; Construct is its reference runtime. Trying the whole stack costs nothing to start.

• Free tier — 5,000 nodes (5× the previous limit, bumped for Construct GA). Matching ingest and retrieval limits. Real evaluation territory for solo use, not a demo cap.
• 30-day Studio trial — unlocks the moment Construct stores its first memory, no credit card. 500,000 nodes, cross-session recall, audit visibility. Whatever you build during the trial, you keep when you revert to free; we don't claw back data.
• Referrals — each successful referral earns you another 30 days of Studio, stackable up to 3 (90 days). Beyond the cap, additional referrals convert to account credit. Friend signs up via your link and ingests their first memory; you both win.
• Inactivity — accounts unused for 90 days move to cold storage, never deleted. Log back in and the graph re-indexes within minutes. The product promise is we don't forget; that includes your account.
• Self-host — available on Enterprise (closed-source license). Email enterprise@kumiho.io or see kumiho.io/pricing.

Full tier matrix and per-feature limits at kumiho.io/pricing.

Web Dashboard & UI

The embedded web frontend (http://127.0.0.1:42617) is a single pane over every layer of the stack — 18 app routes built with React, TypeScript, Tailwind CSS, and Vite, then baked into the Rust binary at compile time via rust-embed. The primary sidebar exposes 17 of them; Workflow Runs (/runs) is a routed page reached contextually from workflow and dashboard links rather than the sidebar itself. One binary. One entry point. The whole signal.

The dashboard's primary navigation is organized into three sidebar sections (Orchestration, Operations, Inspection — see web/src/construct/components/layout/construct-navigation.ts).

Core Views — Orchestration

Live Workflow Execution View

When a workflow runs, you watch the signal propagate:

• Interactive DAG graph — nodes are steps (agent, shell, output, notify, etc.), edges are dependencies. Colors shift in real time as steps move through pending → running → completed/failed. The topology breathes.
• WebSocket event streaming — agent.started, agent.tool_use, agent.completed, agent.error events arrive as they happen.
• Step detail panel with three tabs:
  • Live Events — real-time event feed for the selected step
  • Tool Calls — detailed agent activity from RunLog (tool name, arguments, results, status) fetched via REST on demand
  • Output — the agent's final message/deliverable
• Per-agent RunLog — every call, argument, result, and error committed to disk as JSONL and queryable via GET /api/workflows/agent-activity/{agent_id} with views: summary, tool_calls, messages, errors, full.

Operations

Inspection

Operator Chat (Header Dropdown)

The Operator isn't only available through workflows — every page in the dashboard exposes a one-click chat dropdown from the header. Drop it down, ask a question, get an answer streamed back from the same Operator that drives your workflows. The chat tab and a terminal tab live side-by-side, so you can switch between asking and inspecting without leaving the page you're on.

Backed by the same /ws/chat endpoint listed below, with auto-focus on open and per-route session memory so context carries across navigation.

Real-time Capabilities

• WebSocket Chat (/ws/chat) — streaming agent responses with token-by-token rendering
• Canvas WebSocket (/ws/canvas/{id}) — live HTML/CSS/JS preview with iframe rendering and frame history
• Node Status WebSocket (/ws/nodes) — multi-node capability discovery and status
• PTY Terminal WebSocket (/ws/terminal) — interactive shell over WebSocket
• MCP Session Event WebSocket (/ws/mcp/events) — proxy to the in-process MCP server's session events
• SSE Event Stream (/api/events) — server-sent events for dashboard and activity updates
• SSE Daemon Log Stream (/api/daemon/logs) — streaming daemon log tail

The Operator (Workflow Orchestration)

The Operator is Construct's hand on the controls — a Python MCP server that drives declarative YAML workflows through 20 step types and several advanced orchestration patterns. Agents run inside the Construct; the Operator sees the whole board.

Workflows are stored as YAML artifacts attached to Kumiho revisions — every save creates a new revision, giving you full history, version-to-version diffs, and promotion tagging (e.g., published) without an external version control system. The on-disk YAMLs under ~/.construct/workflows/ use a two-tier layout: the base file (name.yaml) is your editable working copy, discovered by the filesystem scan, while each save freezes a snapshot as name.r{N}.yaml bound to revision N as an immutable artifact via file:// URI. The .r{N} files are skipped by directory scans and reachable only through kref resolution — so running an older revision is just kref://...#rN → Kumiho looks up the artifact URI → loader reads that exact frozen YAML from disk. The revision graph is the source of truth; the disk layout is just where the artifact bytes happen to live. Multi-agent patterns like supervisor, group_chat, map_reduce, handoff, and human_approval are first-class step types, so a multi-agent pipeline reads end-to-end in one file without a Python interpreter in the loop. See WORKFLOWS.md for the full DSL reference.

Step Types

Canonical types from StepType in operator-mcp/operator_mcp/workflow/schema.py.

Editor actions like action: notify are resolved during loading via ACTION_DEFAULTS in workflow/schema.py; notify itself is also a real StepType.

Orchestration Patterns

Parallel Execution — concurrent step groups with three join strategies (ALL, ANY, MAJORITY) and configurable concurrency limits (1-10).

Map-Reduce — fan task to N parallel mapper agents, then a reducer synthesizes. Semaphore-controlled concurrency with optional halt-on-failure.

Supervisor — LLM-driven dynamic delegation loop. The supervisor decomposes tasks and selects specialist agents from the pool (trust-informed), iterating through DELEGATE/COMPLETE/REQUEST_INFO decisions.

Group Chat — moderated multi-agent discussion with topic framing. Supports round-robin turn-taking or moderator-selected next speaker. Produces structured synthesis (summary, consensus, conclusions, open questions).

Handoff — agent-to-agent context transfer preserving last message, files touched, and tool call summaries. Records HANDED_OFF_TO edges in Kumiho for provenance.

Refinement Loop — creator/critic pattern with structured quality scoring (0-100), verdict classification (APPROVED/NEEDS_CHANGES/BLOCKED), and fallback ladder.

Variable Interpolation

Workflow steps support template interpolation across 9 namespaces:

${inputs.field}          — Workflow input parameters
${step_id.output}        — Step text output
${step_id.status}        — Step status
${step_id.output_data.k} — Structured output field
${step_id.files}         — Comma-separated file list
${step_id.agent_id}      — Agent ID that executed step
${loop.iteration}        — Current goto iteration count
${env.VAR}               — Environment variables
${run_id}                — Workflow run ID

Execution Features

• Dependency ordering — depends_on with topological sort and circular dependency detection
• Retry — per-step retry (0-5) with configurable delay
• Checkpointing — auto-save to ~/.construct/workflow_checkpoints/ for crash recovery and resume
• Dry run — validate syntax and dependencies without execution
• Condition evaluation — expression-based branching over step results
• Per-step timeout — default 300s, configurable per step
• RunLog JSONL — per-agent persistent audit trail at ~/.construct/operator_mcp/runlogs/

Reactive Graph — Tag-Triggered Workflows

The Kumiho memory graph isn't just storage — it's the event bus. When a workflow's output step publishes an entity (kind + tag), the daemon emits a revision.tagged event. Any workflow with a matching triggers: block launches automatically, with trigger metadata mapped into its inputs:

triggers:
  - on_kind: "qs-arc-plan"      # Watch for this entity kind
    on_tag: "ready"             # When tagged with this
    input_map:
      arc_kref: "${trigger.entity_kref}"
      arc_name: "${trigger.metadata.arc_name}"

This turns the graph into a reactive substrate: revising or tagging a Kumiho item is a side-effect-bearing action that fans out into downstream pipelines — no cron, no external webhook, no glue script. Workflow A publishes → Workflow B fires → Workflow C resolves the cursor → and so on, all driven by the data shape rather than orchestration code. Cron triggers (cron: "0 9 * * 1") coexist for time-based schedules. See WORKFLOWS.md for chaining patterns and the multi-run continuity recipe.

Agent Pool & Templates

Reusable agent definitions stored in ~/.construct/operator_mcp/agent_pool.json and synced to Kumiho under Construct/AgentPool/.

Template Fields

Pool Operations

• Keyword search across name, role, capabilities, description
• Template validation quality gates before use
• High-performing templates surface first via usage tracking
• Integration with ClawHub for publishing and installing community templates

Trust & Reputation System

Every agent execution is scored. Reputation is not assumed — it's earned, recorded, and queryable in Kumiho under Construct/AgentTrust/.

Outcome weights: success = 1.0, partial = 0.5, failed = 0.0

Trust scores inform the Supervisor pattern's agent selection — higher-trust agents are preferred for delegation. Scores are recorded via tool_record_agent_outcome and retrieved via tool_get_agent_trust (sorted by score descending).

A2A Protocol Support

Construct implements the Google Agent-to-Agent (A2A) protocol for interoperability with external agent systems.

• Discovery — HTTP GET to /.well-known/agent-card.json returns agent capabilities, skills, and identity
• Task lifecycle — JSON-RPC 2.0: message/send (create), tasks/get (poll), tasks/cancel
• Registry — unified search across local Construct templates and external A2A agents
• Retry — up to 2 retries with exponential backoff
• Workflow integration — type: a2a workflow steps with explicit agent URL, message, and timeout

Kumiho Memory Integration

Kumiho is the sole persistent backend. Everything the system knows lives here, as graph-native items with full versioning, provenance tracking, and edge relationships. If it happened, there is a trace.

The namespaces below are Operator/Construct conventions — normal Kumiho spaces under space_prefix = "Construct" (set in config.toml) and, for skills, under KUMIHO_MEMORY_PROJECT (default CognitiveMemory). They are not schema-enforced typed namespaces.

For the integration patterns — engage/reflect, capture types, provenance edges, space organisation, skill discovery — see docs/contributing/kumiho-memory-integration.md.

Additional Features

• ClawHub Marketplace — publish, search, and install agent templates, skills, and team configurations from a shared registry (src/gateway/api_clawhub.rs)
• Multi-Node Distribution (src/nodes/) — distribute agent workloads across remote nodes via WebSocket for horizontal scaling
• Cross-Session Continuity — session journals capture handoff notes; Kumiho archival lets a new session resume with full recall
• Goal Hierarchy — three-tier tracking (strategic/tactical/task) with graph-persisted status, dependencies, and progress
• Skill Library (src/skills/, CognitiveMemory/Skills/) — agents discover, register, and execute reusable skills shared across the runtime; markdown prompts plus SKILL.toml metadata, addressable as Kumiho krefs
• Self-Improving Skills (src/skills/auto_improve.rs, effectiveness.rs, auto_rollback.rs) — the operator records per-call success/failure outcomes; recency-weighted effectiveness scores surface regressing skills; an LLM rewrites their markdown prompts; the new content publishes as a fresh Kumiho-versioned revision tagged published (with auto-rollback if the rewrite itself regresses)
• Audit Trail (src/security/audit.rs) — Merkle hash-chain tamper-evident logging with cryptographic verification
• Cost Tracking (src/cost/) — per-model token and cost breakdown with budget governance at agent or system level
• Cron Scheduling (src/cron/) — recurring, one-shot, and interval jobs with history and catch-up behaviour
• Device Pairing (src/security/pairing.rs) — 6-digit code-based device authentication; optional WebAuthn hardware keys (--features webauthn)
• Approval Gateway (src/approval/, /api/workflows/runs/{id}/approve) — human-in-the-loop approvals with dashboard toaster
• Hooks (src/hooks/) — built-in and user-defined hook runners with a Claude Code hook endpoint (POST /hooks/claude-code)
• Routines (src/routines/) — event-matched routines that trigger based on incoming events
• SOP Engine (src/sop/) — standard-operating-procedure dispatch with conditions and metrics
• Observability (src/observability/) — OpenTelemetry, Prometheus (/metrics), DORA metrics, verbose/log sinks, runtime trace
• Health & Heartbeat (src/health/, src/heartbeat/) — liveness/readiness, heartbeat engine and store for daemon self-checks
• Doctor (src/doctor/) — diagnostics for daemon/scheduler/channel freshness and model/trace sub-commands
• E-Stop (src/security/estop.rs) — emergency stop with level engagement (network-kill, domain-block, tool-freeze) and resume
• Verifiable Intent (src/verifiable_intent/) — cryptographic issuance/verification for agent-action intent receipts
• RAG (src/rag/) — retrieval-augmented helpers that layer over the memory backends
• Multimodal (src/multimodal.rs) — image, voice, and media ingestion primitives shared across channels
• Runtime Sandboxing (src/runtime/, src/security/) — native, Docker, and WASM runtimes; Seatbelt/Landlock/Firejail/Bubblewrap sandbox wrappers; Nevis secrets, domain matching, prompt guard
• Tunnels (src/tunnel/) — Cloudflare, ngrok, Pinggy, Tailscale, OpenVPN, and custom tunnel providers to expose the gateway
• MCP Server (src/mcp_server/) — in-process MCP server with session registry, progress wrapping, and skills-as-tools
• ACP Server — JSON-RPC 2.0 over stdio for IDE integration (construct acp)
• WASM Plugins (src/plugins/, --features plugins-wasm) — load signed WASM tools and channels at runtime
• Onboard Wizard (src/onboard/) — interactive and quick-mode first-run configuration
• OS Service Management (src/service/) — launchd/systemd/OpenRC install for construct daemon
• Update Pipeline (src/commands/update.rs) — 6-phase update with preflight, backup, validate, swap, smoke test, and auto-rollback
• Internationalization (src/i18n.rs) — runtime locale; supported docs locales: en, ko, vi, zh-CN

Hardware & Peripherals

Construct runs as a single Rust binary on x86_64 and arm64 Linux (including Raspberry Pi 3/4/5), macOS, and Windows — the release profile is tuned for low-memory targets (codegen-units = 1, opt-level = "z", panic = "abort"). Full features — persistent memory, multi-agent workflows, the embedded dashboard — require an out-of-process Kumiho memory service and Python 3.11+ for the Operator MCP; without them, Construct degrades gracefully to a stateless single-agent runtime.

Embedded boards are supported as peripherals driven over serial/USB from a Construct host, not as standalone Construct runtimes. Running the full daemon on bare microcontrollers is an explicit non-goal — the host does the thinking, the board does the I/O.

Agent tools expose these as LLM-callable surfaces, so a prompt like "blink the ACT LED three times and then read the I2C sensor on 0x48" dispatches through the same tool loop as a file edit. See docs/hardware/ for per-board setup and the host-mediated vs. edge-native tier model.

REST API

The gateway exposes 90+ REST endpoints and 5 WebSocket routes grouped by domain. All authenticated routes require a bearer token under /api/.

Quick Start

One-command install (auto-handles Rust, sidecars, onboard)

git clone https://github.com/KumihoIO/construct-os
cd construct-os

./install.sh          # macOS / Linux / WSL
# or
.\setup.bat           # Windows (PowerShell — note the leading .\)

PowerShell note. PowerShell does not run scripts from the current directory unless you prefix with .\. If you see "setup.bat is not recognized as a name of a cmdlet", use .\setup.bat. From cmd.exe, plain setup.bat works.

The installer auto-installs Rust via rustup if missing, builds construct, installs the Kumiho + Operator Python MCP sidecars under ~/.construct/, runs construct onboard for interactive provider + API-key setup, and opens the dashboard at http://127.0.0.1:42617.

Once installed:

construct gateway                  # start the HTTP gateway + dashboard
construct agent -m "Hello"         # one-shot message
construct status                   # health check
construct doctor                   # diagnose config / sidecar / channel issues
construct daemon                   # long-running autonomous runtime (service-managed)

From source (developers)

cargo build --release --locked
./scripts/install-sidecars.sh      # or scripts\install-sidecars.bat on Windows
./target/release/construct onboard
./target/release/construct gateway

Add --features channel-matrix,channel-lark,browser-native,hardware,rag-pdf,observability-otel for the full build; see Cargo.toml for the full feature matrix.

Prerequisites

• Rust stable (1.87+) — install.sh / setup.bat will install it via rustup if missing.
• Python 3.11+ — required for the Kumiho and Operator Python MCP sidecars.
• Node.js 20+ — optional, only needed to rebuild the embedded React dashboard from source (cd web && npm install && npx vite build). The dashboard is re-embedded into the Rust binary at compile time via rust-embed.
• Kumiho endpoint — an HTTP endpoint discoverable via [kumiho].api_url in ~/.construct/config.toml. Default points at the kumiho-FastAPI BFF (https://api.kumiho.cloud) that fronts the managed control plane; free tier is 5,000 nodes, sign up at kumiho.io. Self-host is available on Enterprise. Without a reachable Kumiho endpoint Construct runs statelessly. See docs/setup-guides/kumiho-operator-setup.md.
• Disk / RAM — source build needs ~6 GB free disk and ~2 GB free RAM; prebuilt binary is ~200 MB.

Sidecar re-install. To re-run sidecar install independently of the main bootstrap:

• construct install --sidecars-only — cross-platform; embedded in the construct binary, runs the right script for your OS. Use this once you have construct on PATH.
• ./scripts/install-sidecars.sh / scripts\install-sidecars.bat — same logic, straight from a source checkout.

Both paths are idempotent — they never overwrite an existing config.toml, .env, or user-authored launcher.

CLI Commands

Top-level construct subcommands (from src/main.rs). Full reference: docs/reference/cli/commands-reference.md.

Frontend Development

cd web
npm install
npm run dev          # Vite dev server with hot reload

# Production build (embedded into Rust binary)
npx vite build       # outputs to web/dist/
cd .. && cargo build --release  # re-embeds frontend via rust-embed

See docs/setup-guides/dashboard-dev.md for the full frontend development guide.

Configuration

Construct uses TOML configuration at ~/.construct/config.toml:

default_provider = "anthropic"
api_key = "sk-ant-..."

[kumiho]
enabled = true
mcp_path = "~/.construct/kumiho/run_kumiho_mcp.py"
space_prefix = "Construct"
api_url = "https://api.kumiho.cloud"      # or your self-hosted URL on Enterprise

[operator]
enabled = true
mcp_path = "~/.construct/operator_mcp/run_operator_mcp.py"

See docs/reference/api/config-reference.md for the full reference covering providers, channels, tools, security, and gateway settings.

Tech Stack

Documentation

• Documentation hub: docs/README.md — entry points by audience
• Unified TOC: docs/SUMMARY.md
• Setup & onboarding: docs/setup-guides/ — one-click bootstrap, Kumiho/Operator sidecars, Windows, dashboard dev, channels
• Reference (CLI / API / config): docs/reference/
• Operations runbook: docs/ops/
• Security: docs/security/ — sandboxing, audit logging, Matrix E2EE, agnostic security model
• Hardware & peripherals: docs/hardware/
• Integration patterns: docs/contributing/kumiho-memory-integration.md
• Architecture (ADRs): docs/architecture/
• Localized hubs: 한국어 · Tiếng Việt · 简体中文

Related projects

• Kumiho — graph memory backend. SDKs at github.com/KumihoIO/kumiho-SDKs; pricing and self-host at kumiho.io/pricing.
• ZeroClaw — upstream Rust agent runtime that Construct's core forks from. github.com/zeroclaw-labs/zeroclaw.
• OpenClaw — separate TypeScript agent platform; Construct can import its data via construct migrate. github.com/openclaw/openclaw.

License

Construct (this repository) is dual-licensed at your option under:

• MIT
• Apache License 2.0

Both licenses preserve the upstream Copyright (c) 2025 ZeroClaw Labs per fork-attribution requirements; see NOTICE and docs/upstream/zeroclaw-attribution.md.

The Kumiho server (the control plane where Construct's memory ultimately lives) is not covered by these licenses. It is reached over HTTP through the kumiho-FastAPI BFF at api.kumiho.cloud, and is offered as a managed service; the Kumiho SDKs are open source at github.com/KumihoIO/kumiho-SDKs. Self-hosting the Kumiho server is available on Enterprise (closed-source license) — see kumiho.io/pricing.

Contributions to this repository are accepted under the dual license model; the Apache 2.0 patent grant protects all contributors. See docs/contributing/cla.md.