🌳 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?

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) │
└──────────┘     └──────────┘     └──────────────┘
                                         │
                                         ▼
                                  Manual reconciliation
                                  required (sparx reconcile)

Other frameworks retry (duplicate charges) or ignore (lost money). OAK is honest.

🧬 On-Device Continual Learning

Your agent gets smarter with every correction — entirely on-device, with mathematical privacy guarantees.

$ sparx learn correct
# Last response was wrong? Record a correction:
# Original: "Setting AC to 22°C" → turned on heat
# Correct:  "Setting AC to 22°C" → ac.setCooling(22)

$ sparx learn status

Learning Status
═══════════════
  Adapter:    v3 (merged 2 hours ago)
  Corrections: 47 recorded, 38 trained
  Privacy:    ε = 2.1 / budget 8.0 (73% remaining)
  Quality:    perplexity 12.3 → 11.1 (↓9.7%)
  Next train: idle + charging + cool (estimated 3:00 AM)

$ sparx learn train
# ⚙️  QLoRA fine-tuning with DP-SGD...
# ├─ Batch: 38 corrections
# ├─ Privacy: Rényi DP, ε = 0.4 this round
# ├─ Validation: perplexity 12.3 → 11.1 ✓ (improved)
# └─ Adapter merged: v3 → v4

Why this matters:

• No cloud training — corrections never leave the device
• Differential privacy — DP-SGD with configurable ε budget, mathematically bounded information leakage
• Quality guard — perplexity validation before/after; auto-rollback on degradation
• Idle scheduling — trains only when NPU idle + charging + thermally cool
• Progressive merge — weighted adapter averaging prevents catastrophic forgetting

The more you use it, the better it gets. Your data stays yours.

📚 More Features

Evaluation Results

Run ./eval/run_all.sh to reproduce these results.

Technical Report

• Technical Report — detailed evaluation methodology, results analysis, and system design decisions
• Why On-Device? — rationale for on-device agent execution over cloud-based alternatives

Reproducing Results

# Build evaluation suite
cd build && cmake .. -DBUILD_EVAL=ON && make -j$(nproc)
# Run all evaluations
./eval/run_all.sh
# Results appear in eval/results/

📦 Examples

git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent

cd examples/automotive_assistant && sparx run

# "Turn on AC, set to 22°C"      → 87ms
# "Navigate to nearest charger"   → 1.2s (inference)
# "What's my tire pressure?"      → 0.03ms (deterministic)

🔌 Supported Hardware

Develop on any machine (CPU). Deploy to NPU for production:

📐 Project Structure

MasterAgent/
├── cli/                    # Sparx CLI (commands + strategic features)
│   ├── include/            # Public headers
│   │   ├── sparx_speculative.h      # Speculative execution
│   │   ├── sparx_formal_verify.h    # CTL* model checker
│   │   ├── sparx_mesh.h             # Agent mesh protocol
│   │   ├── sparx_learning.h         # Continual learning
│   │   └── sparx_constrained_decode.h
│   └── src/                # Implementations (~5,500 LOC strategic features)
├── include/master_agent/   # Core kernel API
│   ├── orchestrator/       # DAG task execution
│   ├── inference/          # Model runtime abstraction
│   ├── atomic_service/     # MCP tool integration + WAL
│   ├── intent/             # Intent recognition engine
│   ├── skill/              # Deterministic skill engine
│   ├── memory/             # Short-term context
│   └── transport/ipc/      # Inter-process communication
├── src/                    # Core kernel implementation (~40,000 LOC)
├── tests/                  # 19 test suites + 5 strategic feature tests
├── examples/               # Ready-to-run example agents
├── docs/                   # Architecture docs + ROADMAP
└── .github/workflows/      # CI/CD (8-platform release)

🗺️ Roadmap

See docs/ROADMAP_v3.md for the full plan.

📚 Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

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

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

Good first issues: GitHub Issues

❓ FAQ

📄 License

Apache 2.0 — see LICENSE

💬 Community

• GitHub Discussions
• GitHub Issues
• Email: dev@opensparc.com

npm install -g @sparx/cli && sparx init my-agent

npm install -g @sparx/cli && sparx demo automotive

🧠 为什么选 OAK？

核心理念： OAK 之于 Agent OS，如同 Linux 内核之于 Android/Ubuntu。我们不做完整操作系统 — 我们提供开源内核层，车企、手机厂商、机器人公司基于 OAK 自研专属 Agent OS。

⚡ 快速开始

# 安装
npm install -g @sparx/cli

# 初始化项目
sparx init my-agent && cd my-agent

# 下载模型（530MB，1-2 分钟）
sparx pull qwen2.5-0.5b-instruct

# 运行
sparx run

> 你好
✓ route=deterministic  skill=hello  0.02ms  (未调用模型)

> 法国的首都是哪里？
✓ route=inference  ttft=142ms  total=1830ms  tokens=28
  法国的首都是巴黎。

💡 不装模型也能用 — 确定性技能照常工作，只有开放问题需要模型。

💎 核心特性

🔮 投机执行 — 预测你的下一步

预测用户意图，NPU 空闲时预计算结果。命中缓存时 0.11 μs 响应。

🛡️ 形式化验证 — 执行前证明安全

CTL* 模型检查 + 偏序归约，在执行前验证计划不会死锁、不会越权、不会超时。

🌐 Agent Mesh — 零配置多设备协作

mDNS 发现 + CRDT 状态同步 + Merkle 反熵。你的手机、车机、电脑自动组网，将任务路由到最强设备。

🧱 UNKNOWN 终态 — 业界首创

Agent 崩溃时不盲目重试（重复扣费），不静默忽略（钱丢了）。进入 UNKNOWN 状态，要求显式对账。

🧬 端侧自学习 — 越用越聪明

每次纠正都让 Agent 变强，完全在设备上完成，数学保证隐私：

• QLoRA 微调 — 纠正 → 训练 → adapter 合并，全流程端侧
• 差分隐私 — DP-SGD + Rényi 隐私预算，信息泄露有数学上界
• 质量守门 — 训练前后验证困惑度，退步自动回滚
• 空闲调度 — 仅在 NPU 空闲 + 充电 + 温控正常时训练
• 渐进合并 — 加权平均防止灾难性遗忘

你的数据永远不离开设备。用得越多，越懂你。

📚 更多特性

🔌 支持平台

📦 示例

🗺️ 路线图

详见 docs/ROADMAP_v3.md

📚 文档

• 系统概述
• 构建和测试
• WAL 恢复机制
• MCP 服务开发
• Qualcomm NPU 集成

🤝 贡献

欢迎贡献！详见 CONTRIBUTING_zh-CN.md

git clone https://github.com/OpenSparX/MasterAgent.git
cd MasterAgent
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

📄 许可证

Apache 2.0 — 见 LICENSE

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