Status: v0.9.4 — Security hardening + AlterPlan/Kairos reconciliation + HIVE velocity limits + cerebrex doctor npm install -g cerebrex · docker pull ghcr.io/arealcoolco/cerebrex · or download a self-contained binary from GitHub Releases

Live: Registry UI → https://registry.therealcool.site Live: Trace Explorer → https://registry.therealcool.site/ui/trace Live: Website + Whitepaper → https://therealcool.site

CerebreX is an open-source Agent Infrastructure OS — the complete toolchain developers need to build reliable, observable, and secure AI agents.

Eight modules. One CLI. One registry. One coordination layer.

Full benchmark methodology, raw numbers, and detailed comparisons: BENCHMARKS.md

FORGE  parse + scaffold 20-endpoint OpenAPI spec   →   0.12ms  median
MEMEX  read agent memory index                     →   0.01ms  median
MEMEX  assemble 3-layer context                    →   0.03ms  median
HIVE   classify + route 10-task swarm              →   0.09ms  median
TRACE  record tool-call step                       →  <0.01ms  median  (27,435 ops/s)
All benchmarks                                     →  100% success rate

CerebreX starts 26x faster than LangChain and 42x faster than CrewAI.
Bun runtime + single bundled file vs Python's large import tree.

LangChain is a composition library — it connects existing tools but ships zero infrastructure. Memory requires external Redis/Postgres. Observability requires paying for LangSmith. There's no risk gating, no background daemons, and no MCP generation.

CrewAI orchestrates agents in crews but its memory is SQLite-only and in-process. There's no cloud persistence, no risk classification, and no autonomous daemon. Each agent does what it's told — nothing more.

AutoGen excels at multi-agent conversation but everything runs in-process. No cloud memory, no background loop, no registry, no observability beyond print statements.

CerebreX is purpose-built agent infrastructure: the CLI, the cloud workers, the memory layer, the coordination engine, the observatory, and the package registry — all designed together, all open source, all running on Cloudflare's free tier.

npm install -g cerebrex
cerebrex --help

Or via Docker (no Node.js or npm required):

docker pull ghcr.io/arealcoolco/cerebrex
docker run --rm ghcr.io/arealcoolco/cerebrex --version

# Mount a local directory to access spec files, configs, etc.
docker run --rm -v "$HOME/.cerebrex:/root/.cerebrex" ghcr.io/arealcoolco/cerebrex test run

Or build from source (requires Bun):

git clone https://github.com/arealcoolco/CerebreX.git
cd CerebreX/cerebrex
bun install
cd packages/types && bun run build && cd ../..
cd packages/core && bun run build && cd ../..
cd packages/registry-client && bun run build && cd ../..
cd apps/cli && bun run build
node dist/index.js --help

Generate a production-ready MCP server from any OpenAPI spec:

# From a URL
cerebrex build --spec https://petstore3.swagger.io/api/v3/openapi.json --output ./my-server

# From a local file
cerebrex build --spec ./openapi.yaml --output ./my-server

Output is a Cloudflare Workers project with:

• Zod input validation on every tool
• MCP-compliant stdio/SSE/Streamable HTTP transports
• Ready for wrangler deploy

# Start recording (runs in foreground, default port 7432)
cerebrex trace start --session my-agent --port 7432

# From your agent, push steps:
# POST http://localhost:7432/step
# Body: { "type": "tool_call", "toolName": "listPets", "inputs": {}, "latencyMs": 42 }

# Stop and save
cerebrex trace stop --session my-agent

# View in terminal
cerebrex trace view --session my-agent

# View in visual web dashboard (opens browser)
cerebrex trace view --session my-agent --web

# Or use the hosted Trace Explorer (no CLI required)
# https://registry.therealcool.site/ui/trace

# List all saved sessions
cerebrex trace list

Traces are saved to ~/.cerebrex/traces/.

# Store a value
cerebrex memex set "user-pref" "dark mode" --namespace ui

# Retrieve it
cerebrex memex get "user-pref" --namespace ui

# List all memory
cerebrex memex list

# With TTL (auto-expires after 3600 seconds)
cerebrex memex set "session-ctx" "..." --ttl 3600

# Delete a key
cerebrex memex delete "user-pref" --namespace ui

# List all namespaces
cerebrex memex namespaces

All writes are SHA-256 checksummed. Reads verify integrity before returning. Storage: ~/.cerebrex/memex/<namespace>.json — local, no cloud required.

cerebrex auth login     # store token at ~/.cerebrex/.credentials (mode 0600)
cerebrex auth status    # check current auth state
cerebrex auth logout    # remove stored token

CEREBREX_TOKEN env var always takes precedence over stored credentials.

Registry API: https://registry.therealcool.site Registry UI: https://registry.therealcool.site (browser)

cerebrex auth login                              # authenticate first
cerebrex validate ./my-server                   # validate before publishing
cerebrex validate ./my-server --strict          # + OWASP checks
cerebrex publish --dir ./my-server              # publish to registry
cerebrex install my-mcp-server                  # install from registry

# 1 — Initialize and start the coordinator
cerebrex hive init --name my-hive
cerebrex hive start                     # runs on port 7433

# 2 — Register agents and get JWTs
cerebrex hive register --id researcher --name "Researcher" --capabilities search,fetch
cerebrex hive register --id writer     --name "Writer"     --capabilities write,summarize

# 3 — Start workers (each in its own terminal — they poll and execute automatically)
cerebrex hive worker --id researcher --token <JWT>
cerebrex hive worker --id writer     --token <JWT> --handler ./writer-handler.mjs

# Risk-gated workers — HIGH-risk tasks are blocked by default
cerebrex hive worker --id researcher --token <JWT>                  # blocks fetch, deploy, send
cerebrex hive worker --id researcher --token <JWT> --allow-high-risk # permits all task types
cerebrex hive worker --id researcher --token <JWT> --block-medium-risk # LOW only

# 4 — Send tasks — workers pick them up and execute
cerebrex hive send --agent researcher --type fetch    --payload '{"url":"https://api.example.com/data"}' --token <JWT>
cerebrex hive send --agent writer     --type memex-get --payload '{"key":"research-results"}' --token <JWT>

# 5 — Watch it live
cerebrex hive status

Built-in task types (no --handler file required):

Custom handlers — drop in a JS module when you need more:

// researcher-handler.mjs
export async function execute(task) {
  if (task.type === 'search') {
    const res = await fetch(`https://api.example.com/search?q=${task.payload.query}`);
    return { results: await res.json() };
  }
  throw new Error(`Unknown task type: ${task.type}`);
}

cerebrex hive worker --id researcher --token <JWT> --handler ./researcher-handler.mjs

Swarm strategies — launch multi-agent presets in one command:

# List all strategies and presets
cerebrex hive strategies

# Run a named preset
cerebrex hive swarm research-and-recommend "What is the best vector database in 2026?"
cerebrex hive swarm code-review-pipeline   "Review the auth module for security issues"
cerebrex hive swarm best-solution          "How should we implement rate limiting?"
cerebrex hive swarm product-spec           "Design a real-time collaboration feature"
cerebrex hive swarm content-pipeline       "Write a technical blog post about MCP"
cerebrex hive swarm contract-audit         "Audit this API contract for breaking changes"

With TRACE observability — every task shows up in the visual dashboard:

cerebrex trace start --session my-run
cerebrex hive worker --id researcher --token <JWT> --trace-port 7432 --trace-session my-run
cerebrex trace view --session my-run --web

HIVE runs a local HTTP coordinator with JWT-signed agent authentication. State is persisted to ~/.cerebrex/hive/state.json.

KAIROS is a cloud-native daemon built on Cloudflare Durable Objects. Each agent gets its own persistent process that wakes on a 5-minute tick, consults Claude to decide whether to act, and logs every decision to an append-only audit trail.

# Start a daemon for an agent (via the KAIROS REST API)
POST /v1/agents/my-agent/daemon/start

# Stop it
POST /v1/agents/my-agent/daemon/stop

# View the immutable tick history
GET /v1/agents/my-agent/daemon/log

# Queue a task for the daemon to pick up
POST /v1/agents/my-agent/tasks
{ "type": "fetch", "payload": { "url": "https://api.example.com/data" } }

How it works:

1. The KairosDaemon Durable Object wakes every 5 minutes (configurable via TICK_INTERVAL_MS)
2. It calls Claude with context: agent ID, tick number, pending task count
3. Claude decides whether to act (queue a proactive task) or stay quiet
4. The decision, reasoning, and result are written to an append-only D1 log — agents cannot delete their own history
5. If the Claude API is slow or errors repeatedly, the daemon backs off exponentially (1 min → 30 min cap) before resetting on the next success

Submit a high-level goal; Claude Opus produces a comprehensive execution plan; you review and approve it; all tasks queue simultaneously.

# Submit a goal
POST /v1/ultraplan
{ "goal": "Build a competitive analysis of the top 5 vector databases for our use case" }
# → { planId: "abc123", status: "planning", message: "Opus is thinking..." }

# Poll until ready (usually 30-60 seconds)
GET /v1/ultraplan/abc123
# → { status: "pending", plan: { summary, rationale, tasks, risks, success_criteria } }

# Approve — all tasks queue simultaneously
POST /v1/ultraplan/abc123/approve

# Or reject
POST /v1/ultraplan/abc123/reject

The plan JSON contains:

• summary — one-line description
• rationale — why this approach
• tasks[] — array of { type, description, payload, priority } ready to queue
• risks[] — things that could go wrong
• success_criteria[] — how to know the goal was achieved

Goals are capped at 50,000 bytes to prevent runaway Opus calls.

The CerebreX registry includes a browser-based UI served directly from the Worker — no install required.

Full results with competitive analysis: BENCHMARKS.md

# Run all local benchmarks (no network needed)
cerebrex bench

# Run a specific suite
cerebrex bench --suite forge    # MCP server generation
cerebrex bench --suite memex    # three-layer memory
cerebrex bench --suite hive     # swarm coordination + risk gate
cerebrex bench --suite trace    # observability recording
cerebrex bench --suite registry # package search

# Or run directly with Bun
bun benchmarks/forge-bench.ts
bun benchmarks/memex-bench.ts

Benchmarks use performance.now(), report p50/p95/p99 latency and throughput (ops/s), and run with warmup iterations discarded. CI runs the full suite weekly (Sundays 02:00 UTC). All results in benchmarks/results/.

pip install cerebrex

import asyncio
from cerebrex import CerebreXClient

async def main():
    async with CerebreXClient(api_key="cx-your-key") as client:
        # Write to agent memory
        await client.memex.write_index("my-agent", "# Memory\n- learned today")

        # Assemble a system prompt from all three memory layers
        ctx = await client.memex.assemble_context("my-agent", topics=["context"])

        # Search the registry
        results = await client.registry.search("web-search")

        # Submit a KAIROS task
        task = await client.kairos.submit_task("my-agent", "fetch",
            payload={"url": "https://api.example.com/data"})

asyncio.run(main())

See sdks/python/README.md for the full SDK reference including ULTRAPLAN, TRACE, LangChain integration, and CrewAI integration.

cerebrex test lets you write structured assertions against recorded agent traces — no live model calls needed.

# Scaffold a starter spec file
cerebrex test init

# Run all discovered specs
cerebrex test run

# Run a specific spec with verbose output
cerebrex test run my-agent.test.yaml --verbose

# CI mode (JSON to stdout, exit 1 on failure)
cerebrex test run --ci

# Only run tests tagged "smoke"
cerebrex test run --tag smoke

# Record a saved trace session as a reusable fixture
cerebrex test record <session-id>

# List all discovered spec files
cerebrex test list

# Inspect a spec file
cerebrex test show my-agent.test.yaml

Spec format (my-agent.test.yaml):

name: My Agent Tests

tests:
  - name: search tool called with correct query
    steps:
      - type: tool_call
        toolName: web_search
        inputs:
          query: "CerebreX agent OS"
        latencyMs: 120
      - type: tool_result
        toolName: web_search
        outputs:
          results:
            - title: "CerebreX — Agent Infrastructure OS"
        tokens: 45
    assert:
      noErrors: true
      stepCount: 2
      toolsCalled:
        tools: [web_search]
      steps:
        - at: 0
          toolName: web_search

  # Replay a recorded trace fixture
  - name: matches recorded session
    fixture: my-session.fixture.json
    assert:
      noErrors: true
      stepCount:
        min: 1
      output:
        path: results.0.title
        contains: "CerebreX"

Assertions available: stepCount, tokenCount, durationMs, noErrors, toolsCalled (with ordered/exact modes), per-step checks (type, toolName, outputPath/outputValue, latencyMs), and output (dot-path equals/contains/matches).

Validate your local setup and deployed worker health in one command.

# Full local check (credentials, wrangler.toml, HIVE state, registry ping)
cerebrex doctor

# With live worker connectivity checks
cerebrex doctor --kairos-url https://your-kairos.workers.dev \
                --memex-url  https://your-memex.workers.dev  \
                --api-key    $CEREBREX_API_KEY

# CI-friendly JSON output (exit 1 on any failure)
cerebrex doctor --json

What it checks:

Reconstruct the full execution timeline for any task ID across all local trace sessions:

# Find all trace events referencing a task ID
cerebrex trace task abc123

# Limit to a specific session
cerebrex trace task abc123 --session my-session

# Machine-readable JSON
cerebrex trace task abc123 --json

CerebreX/
├── apps/
│   ├── cli/              # cerebrex CLI — the main published package
│   │   ├── src/
│   │   │   ├── commands/ # build, trace, memex, auth, hive, bench, test, doctor, other-commands
│   │   │   └── core/     # forge/, trace/, memex/, test/ engines + dashboard
│   │   └── dist/         # built output (git-ignored, built by CI)
│   └── dashboard/        # Standalone trace explorer HTML
│       └── src/index.html
├── benchmarks/           # Performance benchmark suite (local + live)
│   ├── forge-bench.ts    # FORGE pipeline timing
│   ├── trace-bench.ts    # TRACE step recording throughput
│   ├── memex-bench.ts    # Three-layer MEMEX operations
│   ├── hive-bench.ts     # Swarm coordination + risk gate
│   ├── registry-bench.ts # Package search + metadata
│   ├── agent-tasks-bench.ts  # Cross-framework comparison scaffold
│   └── src/
│       ├── stats.ts      # p50/p95/p99 helpers
│       ├── types.ts      # BenchmarkResult type
│       ├── reporters/    # console, json, markdown reporters
│       └── adapters/     # cerebrex adapter (5 standardized tasks)
├── sdks/
│   └── python/           # Python async SDK (pip install cerebrex)
│       ├── src/cerebrex/ # CerebreXClient + module sub-clients
│       ├── tests/        # pytest test suite with pytest-httpx mocks
│       └── examples/     # quickstart, langchain_integration, crewai_integration
├── workers/
│   ├── registry/         # Cloudflare Worker — live registry backend + Web UI
│   │   ├── src/index.ts  # REST API (D1 + KV) + embedded HTML pages
│   │   ├── schema.sql    # D1 database schema
│   │   └── wrangler.toml
│   ├── memex/            # Cloudflare Worker — MEMEX v2 three-layer cloud memory
│   │   ├── src/index.ts  # KV index + R2 topics + D1 transcripts + task_execution_state + autoDream cron
│   │   ├── migrations/   # D1 schema for agents + transcripts + task_execution_state tables
│   │   └── wrangler.toml
│   └── kairos/           # Cloudflare Worker — KAIROS daemon + ULTRAPLAN
│       ├── src/index.ts  # KairosDaemon Durable Object + reconcile() + task queue + ULTRAPLAN
│       ├── migrations/   # D1 schema for daemon_log, tasks, ultraplans
│       └── wrangler.toml
├── packages/
│   ├── core/             # @cerebrex/core — shared utilities
│   ├── types/            # @cerebrex/types — shared TypeScript types
│   ├── registry-client/  # @cerebrex/registry — registry API client
│   └── system-prompt/    # @cerebrex/system-prompt — master system prompt + MEMEX loader
├── .github/
│   └── workflows/
│       ├── ci.yml              # build + typecheck on push/PR
│       ├── publish.yml         # npm publish on GitHub release
│       ├── deploy-registry.yml # auto-deploy registry Worker
│       ├── deploy-memex.yml    # auto-deploy MEMEX Worker
│       ├── deploy-kairos.yml   # auto-deploy KAIROS Worker
│       ├── build-binaries.yml  # build standalone binaries on release
│       ├── benchmarks.yml      # weekly benchmark suite (Sundays 02:00 UTC)
│       ├── test-python.yml     # Python SDK tests (3.10, 3.11, 3.12)
│       └── publish-python.yml  # publish cerebrex to PyPI on release
└── turbo.json

Built security-first, aligned with the OWASP Top 10 for Agentic Applications (2025).

Found a vulnerability? Please read our Security Policy and report it privately.

Contributions are welcome. CerebreX is a solo-built open-source project — PRs, issues, and feedback all help.

git clone https://github.com/arealcoolco/CerebreX.git
cd CerebreX/cerebrex
bun install
cd packages/types && bun run build && cd ../..
cd packages/core && bun run build && cd ../..
cd packages/registry-client && bun run build && cd ../..
cd apps/cli && bun run build
# Open a PR against main

• FORGE — MCP server generation from OpenAPI (v0.1)
• TRACE — Real HTTP event server, step recording + replay (v0.2)
• MEMEX — Persistent agent memory, SHA-256 integrity, TTL (v0.2)
• AUTH — Secure token storage, cerebrex auth login/logout/status (v0.2)
• VALIDATE — Real MCP + OWASP compliance checks (v0.2)
• CI/CD — GitHub Actions build + npm publish pipeline (v0.2)
• npm package live — npm install -g cerebrex (v0.2.1)
• Web dashboard — Visual trace explorer (cerebrex trace view --web) (v0.3)
• Registry backend — Cloudflare Worker + D1 + KV (v0.3)
• HIVE — Multi-agent JWT coordination (init/start/register/status/send) (v0.3)
• Web UI — Registry browser + hosted trace explorer (Worker-embedded) (v0.4)
• Website live — therealcool.site — whitepaper, manifesto, proof of work (v0.7)
• HIVE cloud API — create/manage hives from anywhere via registry backend (v0.7)
• 8 official MCP packages — memex, hive, fetch, datetime, kvstore, github, nasa, openweathermap (v0.7)
• Token self-service — POST /v1/auth/tokens — users can create scoped tokens (v0.7)
• Rate limiting — per-IP + per-token write limits on MEMEX + HIVE (v0.7)
• HIVE worker — cerebrex hive worker — agents that poll, execute, and report back (v0.7.2)
• Built-in task handlers — fetch, memex-set, memex-get, echo, noop (v0.7.2)
• Custom handler modules — --handler ./my-handler.mjs for domain-specific logic (v0.7.2)
• TRACE + HIVE integration — --trace-port + --trace-session on workers (v0.7.2)
• Standalone binaries — cerebrex-linux-x64, cerebrex-linux-arm64, cerebrex-windows-x64.exe attached to every release (v0.8)
• Windows tar fix + credential icacls hardening (v0.8)
• Update checker — cached background check, 24h TTL (v0.8)
• PWA — registry.therealcool.site installable on Android, Chrome OS, iOS Safari (v0.8)
• MEMEX v2 — three-layer cloud memory (KV + R2 + D1) + autoDream nightly consolidation (v0.9)
• KAIROS — autonomous agent daemon (Durable Objects, 5-min tick loop, append-only log) (v0.9)
• ULTRAPLAN — Opus deep-thinking plan → human approval → parallel task execution (v0.9)
• AUTH risk gate — LOW/MEDIUM/HIGH classification on every agent action (v0.9)
• HIVE swarm strategies — parallel, pipeline, competitive + 6 built-in presets (v0.9)
• @cerebrex/system-prompt — master system prompt package + live MEMEX context loader (v0.9)
• Security hardening — risk gate wired into HIVE worker, JWT /token endpoint authenticated, KAIROS exponential backoff + JSON validation, agentId injection prevention (v0.9.1)
• Benchmark suite — p50/p95/p99, forge/trace/memex/hive/registry + cross-framework agent tasks + cerebrex bench CLI command (v0.9.2)
• Python SDK — async httpx client, Pydantic v2, full module coverage, LangChain + CrewAI integrations (v0.9.2)
• Agent test runner — cerebrex test with replay + assertions, fixture recording, tag filtering, CI mode (v0.9.3)
• AlterPlan/Kairos state reconciliation — task_execution_state D1 table in MEMEX, reconcile() in KAIROS heals orphaned tasks and cascades dependency failures (v0.9.4)
• HIVE velocity limits — rolling-window accumulator blocks chained medium-risk attacks; aggregateRiskScore() for full AlterPlan plan scoring; risk_override JWT scope for admin bypass (v0.9.4)
• cerebrex doctor — environment health checker: credentials, wrangler config, stuck HIVE tasks, worker connectivity (v0.9.4)
• cerebrex trace task <id> — reconstruct full execution timeline for any task across all local trace sessions (v0.9.4)
• Dockerfile tsconfig fix, Python SDK v0.9.4 on PyPI, User-Agent updated in registry client (v0.9.4)

CerebreX is open source under the Apache 2.0 License.