@stackbilt/aegis Core

AEGIS

A persistent AI agent on Cloudflare Workers, and agent work you can check without trusting the agent. Published as @stackbilt/aegis-core: deploy it standalone, or extend it as a dependency.

Coding agents report success they didn't achieve. One of ours said it had added two tests and that the suite passed with 15. The suite had 15 tests before it started. (The full story.) AEGIS is built so that nothing the agent says about its work counts as evidence.

Verified work

The sandbox task executor runs a coding task in a disposable Cloudflare Sandbox container. It opens a pull request only if the task's acceptance contract passes, and it checks the contract against facts it gathers itself:

• Scope: the staged diff. Only the files the contract allows, within its line limits.
• Content: required and forbidden strings in the changed files.
• Tests: a fresh vitest run the executor starts after the agent stops, with the pass count read from vitest's JSON report at a path the agent never saw.

{
  "changed_files_only": ["src/slugify.ts", "tests/slugify.test.ts"],
  "max_added_lines": 15,
  "tests": [{ "command": "npx vitest run tests/slugify.test.ts", "passed": 4 }]
}

A failing change opens nothing. A passing one opens a PR with the check report attached. Fork mode does this for repositories you don't own: it forks the repository and opens the PR on the upstream, as any outside contributor would.

The maintainer doesn't have to trust us either. The same contract format runs as a GitHub Action, agent-acceptance, which checks any agent's PR against the contract in the issue it closes.

Live example: fork-canary#7.

• The repository owner wrote the contract in issue #6.
• The executor ran the task and passed the contract 6/6 before publishing.
• The PR, opened from a fork in another organization, says Fixes #6.
• The Action re-ran the tests from the issue's contract and passed it 6/6 on its own.

The two checks agree, and neither relies on the other.

What it doesn't do: judge whether the tests are good tests. It proves scope, content and test counts, so a reviewer starts from verified facts instead of the agent's summary. Setup and limits: docs/sandbox-executor.md.

The agent runtime

Underneath is a persistent agent that keeps identity, memory and state across every interaction. It runs on Workers AI by default, with Claude and Groq as optional executors, and the base deployment fits the Workers free tier. The sandbox executor is opt-in and needs Workers Paid (Containers).

• Cognitive Kernel: Workers AI-first dispatch with optional Claude and Groq executors, plus procedural memory routing.
• Multi-Tier Memory: episodic (what happened), semantic (what matters), procedural (what works) and narrative. Memory consolidates, decays and strengthens over time.
• Autonomous Goals: goals with standing orders, pursued on a schedule, with progress and blockers reported.
• Dreaming Cycle: nightly reflection over conversation history that proposes improvements and tools and consolidates knowledge.
• Runtime Dynamic Tools: prompt-template tools created at runtime, stored in D1, with TTL, garbage collection and auto-promotion.
• Entropy Detection: flags stale tasks, dormant goals and stale agenda items in the daily digest.
• Content and Social: scheduled content generation, plus Bluesky posting and engagement with rate limits.
• Declarative Governance: ADF files hold behavior, constraints and architectural rules as version-controlled configuration.
• MCP Native: a Model Context Protocol server (20+ tools) and client.

Quick Start

You need Node 22+, a Cloudflare account (the free tier works) and npx wrangler login. Then:

git clone https://github.com/Stackbilt-dev/aegis-oss.git
cd aegis-oss/web
corepack enable        # once per machine; provides pnpm
pnpm install
pnpm run setup         # "run" matters: `pnpm setup` is a different, built-in command

setup does the following:

• asks for a name;
• creates the D1 database (or reuses one with that name) and writes wrangler.toml;
• applies the schema;
• deploys;
• sets a generated AEGIS_TOKEN;
• checks /health and confirms the token signs in, then prints your URL and token.

pnpm run setup --dry-run prints every command without changing anything. The manual steps are in docs/getting-started.md.

Visit your Worker URL and sign in with the AEGIS_TOKEN setup printed. The embedded console uses Workers AI for the base chat and voice path; Claude and Groq keys are optional executor upgrades.

Talk to the same deployment from a terminal:

AEGIS_HOST=your-worker.workers.dev AEGIS_TOKEN=your-token npx @stackbilt/aegis-core --quick

Release proof: AEGIS 0.8.0 Proof of Work. Demo path: AEGIS 0.8.0 Demo Script.

Use as a Dependency

Install @stackbilt/aegis-core and compose your own agent:

pnpm add @stackbilt/aegis-core

import { createAegisApp } from '@stackbilt/aegis-core';

const aegis = createAegisApp({
  operator: myConfig,
  routes: [{ prefix: '/', router: myRoutes }],
  scheduledTasks: [myCustomTask],
});

export default {
  fetch: aegis.app.fetch,
  scheduled: (e, env, ctx) => ctx.waitUntil(aegis.runScheduled(buildEdgeEnv(env))),
};

Core provides: kernel, memory, dispatch, base routes, MCP server, scheduled task framework. You provide: operator config, custom routes, integrations, secrets.

Extension interfaces: ScheduledTaskPlugin, ExecutorPlugin, RoutePlugin, McpToolPlugin.

See CONTRIBUTING.md for full documentation.

Architecture

    ┌────────────────────────────────────────────────────────────┐
    │                   COGNITIVE KERNEL                          │
    │                                                            │
    │  Classify → Route (procedural memory) → Execute            │
    │  (intent)   (learned patterns)          (WAI + optional)   │
    │                                                            │
    │  ┌──────────────────────────────────────────────────────┐  │
    │  │              MEMORY TIERS                             │  │
    │  │  Episodic → Semantic → Procedural → Narrative        │  │
    │  │  (events)   (facts)    (skills)     (story arcs)     │  │
    │  └──────────────────────────────────────────────────────┘  │
    │                                                            │
    │  ┌─────────────────┐  ┌──────────────────────────────┐    │
    │  │ DYNAMIC TOOLS   │  │  SCHEDULED TASKS (26 hourly) │    │
    │  │ Runtime-created  │  │  Dreaming | Goals | Entropy  │    │
    │  │ prompt templates │  │  Social | Content | Memory   │    │
    │  └─────────────────┘  └──────────────────────────────┘    │
    └────────────────────────────────────────────────────────────┘

Runtime Dynamic Tools

AEGIS can create its own tools during conversations or autonomously:

POST /api/dynamic-tools
{
  "name": "summarize_pr",
  "description": "Summarize a GitHub PR into 3 bullet points",
  "prompt_template": "Summarize this PR diff into 3 concise bullets:\n\n{{diff}}",
  "executor": "workers_ai"
}

• Tools are parameterized prompt templates stored in D1
• Executed via Workers AI ($0), Groq, or GPT-OSS — no eval(), no code execution
• Self-improvement detects recurring patterns and proposes tools automatically
• Dreaming cycle proposes tools from conversation analysis
• Hourly GC expires unused tools, auto-promotes at 20 invocations
• 50-tool ceiling prevents context bloat
• Available as MCP tools and in the Claude chat loop (dt_* prefix)

Memory System

Memory consolidation runs hourly. The dreaming cycle runs daily — extracts facts, proposes tasks and tools, discovers cross-domain patterns via PRISM synthesis.

Scheduled Tasks

AEGIS runs 26 tasks on an hourly cron, split into heartbeat (always-run) and time-gated phases:

API Surface

REST Endpoints

MCP Tools (20+)

aegis_chat, aegis_memory, aegis_record_memory, aegis_agenda, aegis_add_agenda, aegis_resolve_agenda, aegis_add_goal, aegis_update_goal, aegis_list_goals, aegis_create_cc_task, aegis_list_cc_tasks, aegis_approve_cc_task, aegis_create_dynamic_tool, aegis_invoke_dynamic_tool, aegis_list_dynamic_tools, aegis_publish_tech_post, aegis_inbox_send, aegis_inbox_read, aegis_generate_decision_doc, and more.

Optional Integrations

Tech Stack

• Runtime: Cloudflare Workers (V8 isolates, global edge)
• Database: Cloudflare D1 (SQLite at the edge)
• Base Inference: Cloudflare Workers AI
• Optional Executors: Claude (Anthropic), Groq (Llama 3.3)
• Framework: Hono (lightweight, edge-native HTTP)
• Language: TypeScript (strict mode)
• Protocol: MCP (Model Context Protocol)
• Cost: $0/month hosting (Workers free tier)

Live Example

The production AEGIS instance is live at aegis.stackbilt.dev/health — hit the health endpoint to see real-time kernel status, procedure counts, and memory metrics.

Ecosystem

AEGIS pairs with other Stackbilt open-source tools:

• cc-taskrunner — Autonomous task queue for Claude Code. Safety hooks, branch isolation, PR creation.
• agent-acceptance — The same acceptance contract as a GitHub Action: check any agent's PR against the issue it closes.
• Charter — AI agent governance CLI. Modular .ai/ files replace monolithic CLAUDE.md configs.
• MindSpring — Semantic search over ChatGPT/Claude conversation exports.
• Social Sentinel — Privacy-first social media sentiment monitoring.

Documentation

• Getting Started — Deploy your own instance in 5 minutes
• Architecture — System design, dispatch flow, memory tiers
• Configuration — Full operator config reference
• Memory System — Memory tiers, consolidation, and dreaming cycle
• Connecting MCP Clients — OpenClaw, Claude Desktop, Claude Code, Cursor, and any MCP client
• AEGIS 0.8.0 Demo Script — Browser console plus CLI proof path
• AEGIS 0.8.0 Proof of Work — Release evidence and validation notes
• Sandbox Task Executor — Acceptance-gated pull requests from sandboxed coding tasks, including fork mode
• Publishing — Release workflow, npm trusted publishing, and token fallback

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — see LICENSE.

Credits

Built by Stackbilt. AEGIS is the cognitive kernel powering the Stackbilt platform.