🌳 OAK — Open Agent Kernel

The Linux kernel for AI agents. Build agents that run 100% on-device. No cloud. No latency. No data leaks.

构建 100% 端侧运行的 AI Agent。无云端依赖，无网络延迟，无数据泄露。

⚠️ Status: Alpha — Core kernel is functional. APIs are unstable. Contributions welcome.

git clone https://github.com/OpenSparX/MasterAgent.git && cd MasterAgent
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)

Quick Start · Why OAK? · Docs · 中文文档

⚡ 30-Second Demo

$ cmake -B build && cmake --build build -j$(nproc) && ctest --test-dir build

[100%] Built target bench_strategic
Test project /home/you/MasterAgent/build
    Start 1: test_integration_speculation
1/5 Test #1: test_integration_speculation .....   Passed    0.8 sec
    Start 2: test_orset
2/5 Test #2: test_orset .......................   Passed    0.4 sec
    Start 3: test_merkle
3/5 Test #3: test_merkle ......................   Passed    0.4 sec
    Start 4: test_embedding
4/5 Test #4: test_embedding ...................   Passed    0.4 sec
    Start 5: bench_strategic
5/5 Test #5: bench_strategic ..................   Passed    2.9 sec

100% tests passed, 0 tests failed out of 5

The OSS build compiles and tests the strategic features: speculative execution, CRDT mesh sync, formal verification, and embedding search. The full CLI (with model inference) requires the kernel runtime — see Architecture.

🧠 Why OAK?

⚡ Sub-100ms

No network round-trip. 80% of requests resolve via pattern matching in microseconds. The other 20% run local LLM inference.

🔒 Private by Default

Data never leaves the device. No telemetry. No cloud calls. Encrypted-at-rest storage with device-bound keys.

🔋 NPU-Optimized

Develop on CPU anywhere. Deploy to Qualcomm NPU for 14× speedup at 3.5× less power. Same code, different backend.

How OAK compares

🚀 Quick Start

Build from Source

# Prerequisites: CMake 3.18+, C++17 compiler (GCC 9+, Clang 11+)
git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DMASTER_AGENT_BUILD_CLI=ON \
      -DMASTER_AGENT_BUILD_TESTS=ON
cmake --build build -j$(nproc)

# Run tests
ctest --test-dir build --output-on-failure

Run with a Local Model (llama.cpp)

# The sparx CLI connects to any llama-server compatible endpoint.
# Start llama-server (install separately: https://github.com/ggml-org/llama.cpp)
llama-server -m your-model.gguf --port 8080

# Run the CLI
./build/cli/sparx run --endpoint 127.0.0.1:8080

Run in Deterministic-Only Mode (No Model Needed)

# Deterministic skills respond without any model loaded
./build/cli/sparx demo automotive

💡 Most intent routing works without a model — only open-ended queries need LLM inference.

📦 What's Open Source

OAK uses an open-core model. This repository contains:

The proprietary kernel runtime handles task orchestration, WAL recovery, and agent dispatch. The strategic feature modules (the algorithmic innovations) are fully open and independently testable.

We're working toward open-sourcing the kernel runtime. Track progress in #1.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Input                               │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  Preprocessing: UTF-8 normalize → parameter extract → memory     │
└──────────────────────────────┬───────────────────────────────────┘
                               ▼
                    ┌─────────────────────┐
                    │  Route Decision     │
                    │  (80% deterministic │
                    │   20% inference)    │
                    └────┬──────────┬─────┘
                         │          │
              ┌──────────▼──┐  ┌───▼────────────┐
              │ Skill Engine │  │ LLM Inference  │
              │ (0.02ms)     │  │ (87ms NPU /    │
              │              │  │  1200ms CPU)   │
              └──────────┬───┘  └───┬────────────┘
                         │          │
                         ▼          ▼
              ┌────────────────────────────────────┐
              │  Task Orchestrator (DAG execution)  │
              │  + WAL Recovery + MCP Services      │
              └────────────────────────────────────┘
                               ▼
              ┌────────────────────────────────────┐
              │  Response (sub-100ms typical)       │
              └────────────────────────────────────┘

Design principles:

• Deterministic first — pattern matching handles 80% of requests at sub-ms latency
• Crash-safe — WAL (Write-Ahead Log) with three terminal states: COMMITTED, FAILED, UNKNOWN
• Hardware-agnostic — same code runs on CPU (dev) and NPU (production)
• Speculate ahead — predict user's next intent and pre-compute during idle time

💎 Key Features

🔮 Speculative Execution

OAK predicts what you'll ask next and pre-computes the answer during idle NPU time.

You: "navigate to office"     ← observed
                               ↓ predictor: P("play music") = 0.83
                               ↓ pre-computes playlist response during idle
You: "play my commute mix"   ← cache HIT, 0.11μs response

🛡️ Formal Plan Verification

Plans are verified for safety before execution using CTL* model checking:

$ sparx plan verify plans/payment-flow.yaml

Plan Verification Report
═══════════════════════════
  ✓ PASS  auth-before-destructive          (12μs)
  ✓ PASS  no-resource-deadlock             (8μs)
  ✓ PASS  all-nodes-terminate              (15μs)
  ✓ PASS  data-flow-integrity              (11μs)
  ✗ FAIL  no-conflicting-destructive       (23μs)
         → Node "charge" and "refund" conflict on resource "wallet"

✗ Plan should NOT be executed. Fix conflicts first.

• CTL* temporal logic (AG, AF, AX, AU, EF, EX)
• Partial-order reduction: 60% state-space reduction on typical plans
• Counterexample traces pinpoint the exact violation path
• Runtime monitor for online verification during execution

🌐 Agent Mesh Protocol

Zero-config multi-device collaboration. Your phone, laptop, and car share agent memory and route work to the most capable device:

$ sparx mesh status

Mesh: oak-home (3 peers, healthy)
┌────────────────┬──────────┬───────┬────────┬─────────┐
│ Device         │ NPU      │ RAM   │ Idle   │ Score   │
├────────────────┼──────────┼───────┼────────┼─────────┤
│ 🚗 Car (local) │ 45 TOPS  │ 16GB  │ yes    │ 0.92    │
│ 📱 Phone       │ 12 TOPS  │ 8GB   │ no     │ 0.45    │
│ 💻 Laptop      │ —        │ 32GB  │ yes    │ 0.38    │
└────────────────┴──────────┴───────┴────────┴─────────┘

CRDT sync: 142 keys, last sync 2s ago
Merkle: roots match (no divergence)

• mDNS/DNS-SD zero-config discovery (_sparx-mesh._tcp.local.)
• CRDT state sync: GCounter, PNCounter, GSet, ORSet (add-wins), LWW-Register
• Merkle anti-entropy: O(log K) divergence detection, not O(K) full scan
• Capability routing: intent → best device by NPU TOPS, model, idle state
• Split inference: partition large models across multiple NPU devices

🧱 Crash Recovery (UNKNOWN State)

Industry first. When an agent crashes mid-operation, the only honest answer is "I don't know if it succeeded."

┌──────────┐     ┌──────────┐     ┌──────────────┐
│ COMMITTED│     │  FAILED  │     │   UNKNOWN    │
│ (success)│     │ (error)  │     │ (crashed     │
│          │     │          │     │  mid-flight) │
└──────────┘     └──────────┘     └──────────────┘
                                         │
                                         ▼