ARK — AI Runtime Kernel

Cut agent costs by 80–90%. Make every step verifiable. Ship agents that don't hallucinate.

ARK doesn't let the model control the system. The runtime does.

It decides which tools run, which model handles each step, how much each decision costs, and whether the output is valid — before anything reaches the user. The model's job is reduced to what it's good at: language. Everything else is governed.

┌─ ARK Agent: Task "ark-run"
│  write a function in Go that reads CSV
│
├─ Task type: coding
├─ Context: loaded 2 tools (42 tokens) [strategy: minimal]
├─ Step 1: ✓ Reasoning verified (confidence: 70%)
│  🧪 Verification: tested (score: 100%)
│  ✅ Compiled
│  ✅ Executed
│  ✅ Tests passed
│  ✅ Lint clean
├─ Step 1: COMPLETE — func readCSV(filePath string) ([][]string, error)
│
└─ Done: 1 step, 637 tokens, 5.6s | Cost: $0.002

════════════════════════════════════════════════════════════
  🧠 ARK Memory — Learning from this execution
════════════════════════════════════════════════════════════

  📥 Ingested 2 new events
  📊 Total experience: 20 memories
  🚀 Context for next run:
     Tool experience: github_search_repos — 100% success (2 uses)
     Past: 'find Python frameworks' succeeded in 2 steps, $0.005
     Past: 'write CSV reader' succeeded in 1 step, $0.002

Why ARK Exists

Current agent frameworks have a fundamental design flaw: they let the model make infrastructure decisions.

The model picks which tools to call. The model decides if the output is good enough. The model controls retry logic. This is like letting a database query decide its own execution plan.

ARK inverts this. The runtime makes every infrastructure decision. The model only does language work.

What Makes ARK Different

1. Cognitive Governor

The governor is the core of ARK. It sits between every model call and the user, enforcing trust.

Task → Classify → Predict failure → Select model → Execute → Verify → Learn → Output
         ↑                                                       │
         └───────────── Registry feeds back ─────────────────────┘

Every output gets a calibrated confidence score — not a flat number, but a signal computed from model history, tool track record, response quality, and grounding:

├─ Step 1: TOOL_CALL — github_search_repos
│  ↳ ✓ Verified (confidence: 88%)     ← model proven on this tool
├─ Step 2: ✓ Reasoning verified (confidence: 87%)  ← grounded in tool data

Confidence is variable, not decorative: - 85-88% → grounded reasoning with proven model+tool combo - 75% → pure reasoning without tool data - 50% → ungrounded (model answered without calling tools) - Below 60% → forces strong model on next step automatically

The governor also: - Predicts failures before execution — skips models with bad track records - Injects experience into prompts ("Previous attempts with this tool had failures. Be more careful.") - Tracks per-task-type performance — learns that gpt-4o-mini handles retrieval but struggles with ranking - Records task-type observations — the registry knows performance per domain, not just per model

2. Per-Step Model Routing

ARK doesn't use one model for everything. Each step gets the right model:

🧠 Model Routing:
  Step 1 [tool_call] gpt-4o-mini  (tool calls are simple, using fast model to save cost)
  Step 2 [complete]  gpt-4o       (final reasoning benefits from strong model)

  Fast model: 1 step | Strong model: 1 step

The router learns from failures. If the fast model fails on a step type, ARK promotes it to the strong model next time. Learning persists across restarts.

3. Search Intelligence (7-Phase Pipeline)

Most agent frameworks send the user's raw query to an API and hope for the best. ARK owns the entire retrieval pipeline:

"find the top 5 most popular JavaScript backend frameworks on GitHub"

Phase 1: Query Intelligence
  → Strip noise: "javascript frameworks"
  → Detect language: JavaScript
  → Add ecosystem hint: +nodejs
  → Skip API language filter for JS (TypeScript repos also needed)

Phase 2: Retrieval
  → GitHub API: sort=stars, order=desc, per_page=30

Phase 3: Language Filter
  → Accept: JavaScript + TypeScript (NestJS, Fastify are TS)
  → Reject: Java, Python, etc.

Phase 4: Junk Filter
  → Remove: awesome-lists, tutorials, cheatsheets, interview prep

Phase 5: Semantic Scoring (3-tier)
  → "web framework" in description  → 2.0× boost (Express, Fastify)
  → No framework signal             → 0.3× penalty (unknown relevance)
  → Anti-signal (ORM, CSS, testing) → 0.01× buried (Mocha, MUI)

Phase 6: Diversity Guard
  → Max 2 repos per owner (prevents Django/Django-channels clustering)

Phase 7: Simplify
  → Essential fields only → LLM explains, never selects

The LLM never decides what's relevant. The runtime ranks. The LLM explains.

4. Code Verification Engine

ARK doesn't trust generated code. It compiles, runs, and tests it before delivering.

├─ Step 1: ✓ Reasoning verified (confidence: 70%)
│  🧪 Verification: tested (score: 100%)
│  ✅ Compiled         ← go build passed
│  ✅ Executed          ← go run passed
│  ✅ Tests passed      ← auto-generated tests passed
│  ✅ Lint clean        ← go vet passed
│  ✔ code_extraction (1 code block(s) found)
│  ✔ structural_lint (0 issues)
│  ✔ constraints (0 violations)
│  ✔ compilation (compiled successfully)
│  ✔ execution (ran without error)
│  ✔ tests (auto-generated tests passed)
│  ✔ lint (0 warnings)

The verification pipeline:

If code fails verification, ARK self-corrects: feeds the compiler error back to the model, forces the strong model, and retries. If it still fails after 2 attempts, ARK refuses to deliver broken code.

5. ARK Memory — Persistent Agent Experience

Every AI agent has amnesia. ARK Memory fixes it.

from ark_memory import Agent, Experience

agent = Agent("my-agent")
exp = Experience(agent)

# Agent learns from every execution automatically
exp.tool_succeeded("github_search_repos", "python frameworks", duration_ms=2500)
exp.tool_failed("web_search", "latest news", error="API key missing")
exp.strategy_learned("coding", "strip test instructions", improvement="eliminated import conflicts")

# Next run — agent queries its own experience
best = exp.best_tool_for("search repositories")
# → github_search_repos: 100% success, avg 2500ms

context = exp.execution_context("coding task")
# → Learned strategies, tool performance, failures to avoid

ARK Memory is a separate Python package (pip install ark-memory) with: - SQLite persistence — survives crashes, zero config - Semantic search via cosine similarity on embeddings - Time decay with configurable half-life - Namespace isolation (per agent, per user, per session) - Anti-redundancy deduplication - Auto-learning collector that ingests Runtime events

6. Unified Execution — One Command, Both Layers

./ark-run.sh "write a function in Go that reads CSV"

Runtime executes the task → emits events → Memory ingests them automatically. Each run makes the next one smarter.

════════════════════════════════════════════════════════════
  🧠 ARK Memory — Learning from this execution
════════════════════════════════════════════════════════════

  📥 Ingested 2 new events
  📊 Total experience: 20 memories
     Tool successes: 7
     Executions: 10

  🚀 Context for next run:
  Tool experience:
    - github_search_repos: 100% success (2 uses)
  Past execution history:
    - Task 'write CSV reader' succeeded in 1 step, $0.002
    - Task 'find Python frameworks' succeeded in 2 steps, $0.005

════════════════════════════════════════════════════════════
  Every run makes the next one smarter.
════════════════════════════════════════════════════════════

7. Decision-Level Cost Attribution

Every step has a price tag. Cost feeds back into ranking.

💰 Cost Report: ark-run
  Total Cost: $0.004840
    Input:  $0.002750 (1100 tokens)
    Output: $0.002090 (209 tokens)

  Decision Cost Graph:
    Step 1 [tool_call: github_search_repos]  $0.000990
    Step 2 [complete]                        $0.003850

5. Task Classification

ARK classifies every task before execution and adapts its behavior:

├─ Task type: ranking          ← detected from "top", "most popular"

6. Adaptive Learning

ARK remembers across runs. Tool scores evolve based on real outcomes.

RUN 1: github_list_repos = 0.55   (no history)
RUN 2: github_list_repos = 0.69   (1 success)
RUN 3: github_list_repos = 0.95   (2 successes, compounding)

RUN 1: github_search = 0.55       (no history)
RUN 2: github_search = 0.42       (1 failure, demoted)

Learning is bounded — history can't dominate. Confidence capped at 0.80. New tools get exploration bonuses. Intent-matching boosts the right tool for the right query.

By the Numbers

Quick Start

git clone https://github.com/atripati/ark.git
cd ark

# No API keys needed for demos
go run ./cmd/ark bench        # see context savings (99.9% reduction)
go run ./cmd/ark demo         # see failure → adapt → recover
go run ./cmd/ark demo-learn   # see ranking improve across 3 runs

# With OpenAI (~$0.005 per task)
export OPENAI_API_KEY=sk-...
export GITHUB_TOKEN=ghp_...

# Run Runtime only
go run ./cmd/ark run agent.yaml --task "find the top 3 Python web frameworks on GitHub"

# Run Runtime + Memory together (one command)
chmod +x ark-run.sh
./ark-run.sh "find the top 3 Python web frameworks on GitHub"

# Install ARK Memory separately
cd ark-memory
pip install -e .
pytest tests/ -v   # 55+ tests

Configuration

name: my-agent
version: "0.1"

model:
  provider: openai           # openai | anthropic | ollama
  name: gpt-4o
  max_tokens: 4096
  strategy: cost_optimized   # single | cost_optimized | quality_first
  fast_model: gpt-4o-mini
  strong_model: gpt-4o

context:
  total_tokens: 200000
  strategy: adaptive
  tool_budget: 10%
  memory_budget: 10%
  conversation_budget: 35%
  max_steps: 5
  timeout_seconds: 120

memory:
  backend: file
  path: "./ark-memory.json"

Connect Any API

tools:
  - name: get_weather
    type: http
    method: GET
    uri: "https://api.openweathermap.org/data/2.5/weather?q={city}&appid=${OPENWEATHER_KEY}"
    description: "get current weather for a city"
    params:
      - city

  - name: slack_post
    type: http
    method: POST
    uri: "https://slack.com/api/chat.postMessage"
    description: "post a message to a Slack channel"
    params: [channel, text]
    headers:
      Authorization: "Bearer ${SLACK_TOKEN}"
    write: true   # requires --allow-write

ARK handles domain allowlisting, parameter validation, cost tracking, and learning for custom tools automatically.

Built-in Tools

12 tools across 4 categories. All ranked, learned, and cost-tracked automatically.

Safety

Safe by default. Dangerous operations require explicit opt-in.

```bash ark run agent.yaml --task "list repos" # ✅ reads work ark run agent.yaml --task "create issue"