|
12 | 12 |
|
13 | 13 | **A persistent AI agent framework for Cloudflare Workers.** |
14 | 14 |
|
15 | | -Cognitive kernel with multi-tier memory, autonomous goal pursuit, a dreaming cycle, and declarative governance. Deploy your own persistent AI co-founder on the edge. |
| 15 | +Cognitive kernel with multi-tier memory, autonomous goal pursuit, a dreaming cycle, runtime tool creation, and 26 scheduled tasks. Deploy your own persistent AI co-founder on the edge. |
16 | 16 |
|
17 | 17 | ## What is AEGIS? |
18 | 18 |
|
19 | | -AEGIS is a framework for building **personal AI agents** that remember everything, pursue goals autonomously, and improve themselves while you sleep. Unlike chat-based AI tools that forget between sessions, AEGIS maintains persistent identity, memory, and state across every interaction. |
| 19 | +AEGIS is a framework for building **personal AI agents** that remember everything, pursue goals autonomously, create their own tools, and improve themselves while you sleep. Unlike chat-based AI tools that forget between sessions, AEGIS maintains persistent identity, memory, and state across every interaction. |
| 20 | + |
| 21 | +The production instance runs 26 scheduled tasks, has executed 236+ autonomous coding sessions, and costs $0/month to host (Cloudflare Workers free tier + Workers AI for inference). |
20 | 22 |
|
21 | 23 | Built on Cloudflare Workers for edge-native deployment. Zero cold starts. Global distribution. Pay-per-request economics. |
22 | 24 |
|
23 | 25 | ### Core Capabilities |
24 | 26 |
|
25 | 27 | - **Cognitive Kernel** — Multi-model dispatch (Claude, Groq, Workers AI) with procedural memory routing. The right model for the right task, automatically. |
26 | 28 | - **Multi-Tier Memory** — Episodic (what happened), semantic (what matters), procedural (what works), narrative (the story arc). Memory consolidates, decays, and strengthens over time. |
27 | | -- **Autonomous Goals** — Set goals and let AEGIS pursue them on a schedule. Progress tracked, blockers surfaced, results reported. |
28 | | -- **Dreaming Cycle** — Nightly self-reflection over conversation history. Discovers patterns, proposes improvements, consolidates knowledge. |
| 29 | +- **Autonomous Goals** — Set goals with standing orders and let AEGIS pursue them on a schedule. Progress tracked, blockers surfaced, results reported. |
| 30 | +- **Dreaming Cycle** — Nightly self-reflection over conversation history. Discovers patterns, proposes improvements, proposes new tools, consolidates knowledge. PRISM synthesis finds cross-domain connections. |
| 31 | +- **Runtime Dynamic Tools** — Create reusable prompt-template tools at runtime during conversations or autonomously via self-improvement. Tools are stored in D1, executed via LLM, with lifecycle management (TTL, GC, auto-promotion at 20 uses). |
| 32 | +- **Entropy Detection** — Monitors for ghost tasks (>7d stale), dormant goals (>14d), and stale agenda items. Calculates system entropy score and surfaces findings in the daily digest. |
| 33 | +- **Social Engagement** — Autonomous Bluesky interaction: likes replies, follows back real accounts, generates on-brand replies via Workers AI. Spam filtering and rate limiting built in. |
| 34 | +- **Content Pipeline** — Scheduled content generation and social media drip posting via AT Protocol. Queue posts, schedule delivery, track engagement. |
29 | 35 | - **Declarative Governance** — ADF (Agent Definition Format) files control behavior, constraints, and architectural rules. Version-controlled agent configuration. |
30 | 36 | - **Operator Identity** — Fully configurable persona, traits, and integration preferences. Your agent, your personality. |
31 | | -- **MCP Native** — Full Model Context Protocol server and client. Connect any MCP-compatible tool. |
| 37 | +- **MCP Native** — Full Model Context Protocol server (20+ tools) and client. Connect any MCP-compatible tool. |
32 | 38 |
|
33 | 39 | ## Quick Start |
34 | 40 |
|
@@ -59,107 +65,140 @@ Visit `https://your-worker.workers.dev` and authenticate with your AEGIS_TOKEN. |
59 | 65 | ## Architecture |
60 | 66 |
|
61 | 67 | ``` |
62 | | - ┌─────────────────────────┐ |
63 | | - │ Operator Config │ |
64 | | - │ (identity, persona, │ |
65 | | - │ integrations) │ |
66 | | - └────────────┬────────────┘ |
67 | | - │ |
68 | | - ┌────────────────────────────▼────────────────────────────┐ |
69 | | - │ COGNITIVE KERNEL │ |
70 | | - │ │ |
71 | | - │ ┌──────────┐ ┌──────────┐ ┌───────────────────────┐ │ |
72 | | - │ │ Classify │→│ Route │→│ Execute │ │ |
73 | | - │ │ (intent) │ │(procedure│ │ Claude / Groq / WAI / │ │ |
74 | | - │ │ │ │ memory) │ │ Composite / Direct │ │ |
75 | | - │ └──────────┘ └──────────┘ └───────────────────────┘ │ |
76 | | - │ │ |
77 | | - │ ┌──────────────────────────────────────────────────┐ │ |
78 | | - │ │ MEMORY TIERS │ │ |
79 | | - │ │ Episodic → Semantic → Procedural → Narrative │ │ |
80 | | - │ │ (events) (facts) (skills) (story arcs) │ │ |
81 | | - │ └──────────────────────────────────────────────────┘ │ |
82 | | - │ │ |
83 | | - │ ┌──────────────────────────────────────────────────┐ │ |
84 | | - │ │ SCHEDULED TASKS (hourly cron) │ │ |
85 | | - │ │ Heartbeat | Consolidation | Goals | Dreaming │ │ |
86 | | - │ │ Curiosity | Reflection | Escalation │ │ |
87 | | - │ └──────────────────────────────────────────────────┘ │ |
88 | | - └──────────────────────────────────────────────────────────┘ |
| 68 | + ┌────────────────────────────────────────────────────────────┐ |
| 69 | + │ COGNITIVE KERNEL │ |
| 70 | + │ │ |
| 71 | + │ Classify → Route (procedural memory) → Execute │ |
| 72 | + │ (intent) (learned patterns) (Claude/Groq/WAI) │ |
| 73 | + │ │ |
| 74 | + │ ┌──────────────────────────────────────────────────────┐ │ |
| 75 | + │ │ MEMORY TIERS │ │ |
| 76 | + │ │ Episodic → Semantic → Procedural → Narrative │ │ |
| 77 | + │ │ (events) (facts) (skills) (story arcs) │ │ |
| 78 | + │ └──────────────────────────────────────────────────────┘ │ |
| 79 | + │ │ |
| 80 | + │ ┌─────────────────┐ ┌──────────────────────────────┐ │ |
| 81 | + │ │ DYNAMIC TOOLS │ │ SCHEDULED TASKS (26 hourly) │ │ |
| 82 | + │ │ Runtime-created │ │ Dreaming | Goals | Entropy │ │ |
| 83 | + │ │ prompt templates │ │ Social | Content | Memory │ │ |
| 84 | + │ └─────────────────┘ └──────────────────────────────┘ │ |
| 85 | + └────────────────────────────────────────────────────────────┘ |
89 | 86 | ``` |
90 | 87 |
|
91 | | -## Configuration |
92 | | - |
93 | | -Copy `src/operator/config.example.ts` to `src/operator/config.ts` and customize: |
94 | | - |
95 | | -```typescript |
96 | | -export const operatorConfig: OperatorConfig = { |
97 | | - identity: { |
98 | | - name: 'Alex', // Your name |
99 | | - possessive: "Alex's", |
100 | | - }, |
101 | | - persona: { |
102 | | - tagline: 'pragmatic technical co-founder', |
103 | | - traits: ['direct', 'systems-thinking', 'builder'], |
104 | | - }, |
105 | | - // ... integrations, products, etc. |
106 | | -}; |
| 88 | +## Runtime Dynamic Tools |
| 89 | + |
| 90 | +AEGIS can create its own tools during conversations or autonomously: |
| 91 | + |
| 92 | +``` |
| 93 | +POST /api/dynamic-tools |
| 94 | +{ |
| 95 | + "name": "summarize_pr", |
| 96 | + "description": "Summarize a GitHub PR into 3 bullet points", |
| 97 | + "prompt_template": "Summarize this PR diff into 3 concise bullets:\n\n{{diff}}", |
| 98 | + "executor": "workers_ai" |
| 99 | +} |
107 | 100 | ``` |
108 | 101 |
|
109 | | -See [docs/configuration.md](docs/configuration.md) for the full reference. |
| 102 | +- Tools are parameterized prompt templates stored in D1 |
| 103 | +- Executed via Workers AI ($0), Groq, or GPT-OSS — no `eval()`, no code execution |
| 104 | +- Self-improvement detects recurring patterns and proposes tools automatically |
| 105 | +- Dreaming cycle proposes tools from conversation analysis |
| 106 | +- Hourly GC expires unused tools, auto-promotes at 20 invocations |
| 107 | +- 50-tool ceiling prevents context bloat |
| 108 | +- Available as MCP tools and in the Claude chat loop (`dt_*` prefix) |
110 | 109 |
|
111 | 110 | ## Memory System |
112 | 111 |
|
113 | | -AEGIS maintains four tiers of memory that work together: |
114 | | - |
115 | 112 | | Tier | Purpose | Lifecycle | |
116 | 113 | |------|---------|-----------| |
117 | 114 | | **Episodic** | Raw interaction logs (intent, outcome, cost) | Created per dispatch, pruned after 30 days | |
118 | 115 | | **Semantic** | Durable facts with topic taxonomy | Promoted from episodic during consolidation | |
119 | 116 | | **Procedural** | Learned patterns (which executor works for which intent) | Updated on every dispatch outcome | |
120 | 117 | | **Narrative** | Story arcs and cognitive state | Generated during dreaming cycle | |
121 | 118 |
|
122 | | -Memory consolidation runs hourly. The dreaming cycle runs daily to reflect on conversation history and discover cross-session patterns. |
| 119 | +Memory consolidation runs hourly. The dreaming cycle runs daily — extracts facts, proposes tasks and tools, discovers cross-domain patterns via PRISM synthesis. |
123 | 120 |
|
124 | 121 | ## Scheduled Tasks |
125 | 122 |
|
126 | | -AEGIS runs these tasks on an hourly cron: |
| 123 | +AEGIS runs 26 tasks on an hourly cron, split into heartbeat (always-run) and time-gated phases: |
127 | 124 |
|
128 | 125 | | Task | Cadence | Purpose | |
129 | 126 | |------|---------|---------| |
130 | | -| Heartbeat | 6h | System health check, dispatch test | |
131 | | -| Consolidation | Hourly | Episodic → semantic memory promotion | |
132 | | -| Goals | 5 of 6 hours | Autonomous goal execution | |
133 | | -| Curiosity | Daily | Research topics from memory gaps | |
134 | | -| Reflection | Weekly | Deep memory reflection cycle | |
135 | | -| Operator Log | Daily | Generate daily activity summary | |
136 | | -| Dreaming | Daily | Nightly self-reflection and pattern discovery | |
137 | | -| Escalation | Hourly | Bump stale agenda item priorities | |
138 | | -| Cognitive Metrics | Daily | Memory health and dispatch quality metrics | |
| 127 | +| Escalation | Hourly | Bump stale agenda priorities | |
| 128 | +| CI Watcher | Hourly | Monitor GitHub Actions runs | |
| 129 | +| ARGUS Notify | Hourly | Classify webhook events, route alerts | |
| 130 | +| Cognitive Metrics | Daily | Classifier accuracy, dispatch cost tracking | |
| 131 | +| PR Automerge | Hourly | Auto-merge approved docs/tests PRs | |
| 132 | +| Consolidation | Hourly | Memory dedup, decay, promotion, dynamic tool GC | |
| 133 | +| Heartbeat | 6h | System health + email digest | |
| 134 | +| Product Health | Hourly | Worker availability checks | |
| 135 | +| Entropy | 6h | Ghost tasks, stale agenda, dormant goals | |
| 136 | +| Social Engage | 6h | Bluesky: like replies, follow back, reply | |
| 137 | +| Content Drip | Hourly | Publish scheduled social posts | |
| 138 | +| Issue Watcher | 2h | Scan GitHub issues, auto-queue tasks | |
| 139 | +| Feed Watcher | 6h | Poll RSS/Atom feeds | |
| 140 | +| Self-Improvement | 6h | Multi-repo codebase scan, tool proposals | |
| 141 | +| Goals | Non-SI hours | Autonomous goal execution with standing orders | |
| 142 | +| Curiosity | Daily | Memory gaps → research dispatch | |
| 143 | +| Dreaming | Daily | Thread review → facts/tasks/tools + PRISM synthesis | |
| 144 | +| Daily Digest | 09 UTC | Co-Founder Brief email | |
| 145 | + |
| 146 | +## API Surface |
| 147 | + |
| 148 | +### REST Endpoints |
| 149 | + |
| 150 | +| Method | Path | Description | |
| 151 | +|--------|------|-------------| |
| 152 | +| GET | `/health` | System health dashboard | |
| 153 | +| GET | `/api/entropy` | Entropy score + ghost items | |
| 154 | +| GET/POST | `/api/dynamic-tools` | CRUD for runtime tools | |
| 155 | +| POST | `/api/dynamic-tools/:id/invoke` | Execute a dynamic tool | |
| 156 | +| POST | `/api/bluesky/post` | Post to Bluesky | |
| 157 | +| GET | `/api/bluesky/feed` | Get author feed | |
| 158 | +| POST | `/api/bluesky/like` | Like a post | |
| 159 | +| POST | `/api/bluesky/repost` | Repost | |
| 160 | +| GET | `/api/bluesky/notifications` | Check notifications | |
| 161 | +| GET | `/api/content-queue` | View scheduled posts | |
| 162 | +| GET | `/llms.txt` | LLM-friendly site description | |
| 163 | + |
| 164 | +### MCP Tools (20+) |
| 165 | + |
| 166 | +`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. |
139 | 167 |
|
140 | 168 | ## Optional Integrations |
141 | 169 |
|
142 | 170 | | Integration | Secret | Purpose | |
143 | 171 | |-------------|--------|---------| |
144 | 172 | | GitHub | `GITHUB_TOKEN` | Repository scanning, issue management, self-improvement | |
145 | 173 | | Brave Search | `BRAVE_API_KEY` | Web research capability | |
146 | | -| Resend | `RESEND_API_KEY` | Email notifications | |
| 174 | +| Bluesky | `BLUESKY_HANDLE` + `BLUESKY_APP_PASSWORD` | Social posting and engagement | |
| 175 | +| Resend | `RESEND_API_KEY` | Email notifications and daily digest | |
147 | 176 | | Memory Worker | Service Binding | Persistent semantic memory with vector search | |
148 | 177 | | TarotScript | Service Binding | Deterministic symbolic reasoning | |
149 | 178 |
|
150 | 179 | ## Tech Stack |
151 | 180 |
|
152 | 181 | - **Runtime**: Cloudflare Workers (V8 isolates, global edge) |
153 | 182 | - **Database**: Cloudflare D1 (SQLite at the edge) |
154 | | -- **AI Models**: Claude (Anthropic), Groq (Llama 3.3), Workers AI (GPT-OSS-120B) |
| 183 | +- **AI Models**: Claude (Anthropic), Groq (Llama 3.3), Workers AI (free inference) |
155 | 184 | - **Framework**: Hono (lightweight, edge-native HTTP) |
156 | 185 | - **Language**: TypeScript (strict mode) |
157 | 186 | - **Protocol**: MCP (Model Context Protocol) |
| 187 | +- **Cost**: $0/month hosting (Workers free tier) |
158 | 188 |
|
159 | 189 | ## Live Example |
160 | 190 |
|
161 | 191 | The production AEGIS instance is live at **[aegis.stackbilt.dev/health](https://aegis.stackbilt.dev/health)** — hit the health endpoint to see real-time kernel status, procedure counts, and memory metrics. |
162 | 192 |
|
| 193 | +## Ecosystem |
| 194 | + |
| 195 | +AEGIS pairs with other Stackbilt open-source tools: |
| 196 | + |
| 197 | +- **[cc-taskrunner](https://github.com/Stackbilt-dev/cc-taskrunner)** — Autonomous task queue for Claude Code. Safety hooks, branch isolation, PR creation. |
| 198 | +- **[Charter](https://github.com/Stackbilt-dev/charter)** — AI agent governance CLI. Modular .ai/ files replace monolithic CLAUDE.md configs. |
| 199 | +- **[MindSpring](https://github.com/Stackbilt-dev/mindspring)** — Semantic search over ChatGPT/Claude conversation exports. |
| 200 | +- **[Social Sentinel](https://github.com/Stackbilt-dev/social-sentinel)** — Privacy-first social media sentiment monitoring. |
| 201 | + |
163 | 202 | ## Documentation |
164 | 203 |
|
165 | 204 | - [Getting Started](docs/getting-started.md) — Deploy your own instance in 5 minutes |
|
0 commit comments