ZQK OS

The Cellular Knowledge Operating System for autonomous agent swarms. This repository is ZQK Core, the open-core community microkernel. Canonical portal: Community First-Run Guide.

Quickstart (5 Minutes)

1. Install or Build

Homebrew (macOS & Linux)

brew tap zqk-os/tap
brew install zqk

GitHub Release Binaries

Pre-compiled release archives and OpenVEX attestations are available at GitHub Releases.

Build From Source

git clone https://github.com/zqk-os/zqk.git && cd zqk
make          # → ./bin/zqk
./bin/zqk --version

2. Seed a Sovereign Cell (Polyglot: Go, Python, TS, Rust)

mkdir my-project && cd my-project
zqk init
zqk quickstart

Do not export ZQK_PROJECT_ROOT in your shell profile. ZQK discovers the nearest .zqk/ membrane from the working tree.

3. Seat Your AI Agent (Cursor, Claude Code, Windsurf, Cline)

zqk system agent-onboard --format json
zqk system start-here

4. Connect via Model Context Protocol (MCP)

zqk mcp install
zqk mcp ensure --tcp 127.0.0.1:8443
# Cursor stdio: zqk mcp cursor-adapter

5. Run Swarms & Live Telemetry

# Run a portable swarm package (local path or remote git URL)
zqk run ./examples/swarms/code-eval/
# Or run from remote git: zqk run https://github.com/zqk-os/swarm-starter-kit

# Launch interactive full-screen terminal mission control
zqk ui

# Stream real-time mutations with the visual ANSI seismograph
zqk state stream --dashboard

---

The Substrate for Living Software: Sovereign Cells. Verified Truth. Autonomous Organisms.

ZQK (Zen Quantum Kernel) is an open-core, distributed Cellular Knowledge Operating System (Cellular OS) engineered in high-performance Go. It fundamentally rejects the status quo of gluing autonomous agents together with fragile Python scripts and chaotic vector swamps.

Instead, ZQK treats multi-agent systems as a biological computing substrate built upon a rigorous microkernel architecture: where individual repositories and services function as autonomous holons—sovereign, self-governing wholes that integrate seamlessly into a collaborative distributed organism.

Your AI agents are coding blind. Dumping uncurated conversation logs into vector lakes produces context decay and runaway hallucination blast radiuses. ZQK provides cellular memory isolation, epistemic hygiene, ambient feedback sensing, and biological self-healing guardrails so agent swarms govern themselves.

Biological Systems & Holonic Architecture

Rather than treating multi-agent work as loose prompt scripts or terminal splits, ZQK introduces four foundational biological primitives:

1. The Cell / Holon (Sovereign Node): Each ZQK kernel is an autonomous holon—simultaneously a complete, self-governing whole and an organic participant in the wider mesh. It maintains authoritative stewardship over its local codebase, tests, and private knowledge graph without relying on bloated global vector lakes.
2. The Membrane (Deterministic Boundaries): A strict multi-plane state machine (Draft → Promoted (via CAS membrane qualification)) ensuring that zero unverified agent mutations ever pollute working code or canonical state.
3. The Nervous System (Active Operational Graph): An active, real-time synaptic state bus driving task execution, causal provenance lineage, and dependency trees—not a passive secondary data lake.
4. The Organism (Inter-Cellular Mesh): Domain-expert kernels communicating over a typed P2P wire protocol to achieve compound objectives without central micromanagement.

Autonomous Memory & Imparted Human Intent

Knowledge in ZQK is never static documentation. It is an active, sensing memory layer:

• Programmed Human Intent: Human goals, non-negotiable rules, architectural invariants, mission, and vision are encoded directly into kernel schema objects (Goal, Policy, InvariantGate). Agents never invent objectives in isolation; their actions are strictly bounded by human-imparted intent.
• Ambient Feedback Sensing: Integrated background daemons monitor filesystem changes, test execution suites, and process drift. The kernel senses when reality diverges from intent and dynamically triggers corrective cycles.
• Temporal Agility (Snapshot, Rollback & Cherry-Pick): Treat knowledge like Git commits. Create atomic cryptographic snapshots, fork or branch memory planes for parallel experimentation, rollback failed excursions, and cherry-pick verified knowledge across cells.
• Laser Context Curation & Token Efficiency: Rather than exhausting LLM context windows on uncurated chat history, ZQK slices precise graph subtrees based on the specific WorkUnit an agent claims—significantly reducing token consumption while maximizing reasoning accuracy.

The 3-Tier Layering Model

Open-Core Boundary: Single Cell vs. Organism Mesh

ZQK follows the classical operating system boundary: POSIX/Kernel primitives are 100% open-source; distributed multi-tenant mesh clustering and fleet governance are commercial.

Core Capabilities

• Cellular Epistemic Hygiene: Cryptographic provenance (parent_hash, agent_id, signature) attached to all mutations.
• Autonomous Project Awareness: Agents query the graph to discover objectives, constraints, and architecture without manual prompting.
• Native Code Search: High-performance in-process AST and trigram search via ./bin/zqk grep (alias zgrep).
• Local-First & Offline-Ready: Pure Go with filesystem & embedded graph storage—zero external cloud dependency required.
• Deterministic Traceability: Every commit and diff links back to verified invariants and backlog work units.

Documentation & Guides

• Community First-Run Guide — Recommended starting point for humans and agents.
• First-Run Object Tutorial — Creating and managing kernel objects.
• Quickstart & MCP Setup — Connecting Cursor, Claude Code, and other LLMs.
• Architecture Guide — Deep dive into the cellular microkernel architecture.
• Contributing — Development guidelines and PR policies.
• Security Policy — Vulnerability reporting and fail-closed security guarantees.

Connect & Community

• Website: zqk.dev
• Documentation Portal: docs.zqk.dev
• General Inquiries: [email protected]
• Technical Support: [email protected]
• Schedule a Call: Book a ZQK Inquiry
• GitHub: zqk-os/zqk

License

Open-Core Community Kernel: Apache License 2.0 (see NOTICE). Enterprise modules and multi-node fleet mesh capabilities are licensed separately.