Skip to content

Commit 4196fd0

Browse files
docs: update README with v1.53–v1.57 features
Add runtime dynamic tools, entropy detection, social engagement, Bluesky integration, content pipeline, PRISM synthesis, GEO discovery. Updated architecture diagram, scheduled tasks table (26 tasks), API surface, ecosystem links. Reflects current production state. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c68b4a4 commit 4196fd0

1 file changed

Lines changed: 103 additions & 64 deletions

File tree

README.md

Lines changed: 103 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,29 @@
1212

1313
**A persistent AI agent framework for Cloudflare Workers.**
1414

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.
1616

1717
## What is AEGIS?
1818

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).
2022

2123
Built on Cloudflare Workers for edge-native deployment. Zero cold starts. Global distribution. Pay-per-request economics.
2224

2325
### Core Capabilities
2426

2527
- **Cognitive Kernel** — Multi-model dispatch (Claude, Groq, Workers AI) with procedural memory routing. The right model for the right task, automatically.
2628
- **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.
2935
- **Declarative Governance** — ADF (Agent Definition Format) files control behavior, constraints, and architectural rules. Version-controlled agent configuration.
3036
- **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.
3238

3339
## Quick Start
3440

@@ -59,107 +65,140 @@ Visit `https://your-worker.workers.dev` and authenticate with your AEGIS_TOKEN.
5965
## Architecture
6066

6167
```
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+
└────────────────────────────────────────────────────────────┘
8986
```
9087

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+
}
107100
```
108101

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)
110109

111110
## Memory System
112111

113-
AEGIS maintains four tiers of memory that work together:
114-
115112
| Tier | Purpose | Lifecycle |
116113
|------|---------|-----------|
117114
| **Episodic** | Raw interaction logs (intent, outcome, cost) | Created per dispatch, pruned after 30 days |
118115
| **Semantic** | Durable facts with topic taxonomy | Promoted from episodic during consolidation |
119116
| **Procedural** | Learned patterns (which executor works for which intent) | Updated on every dispatch outcome |
120117
| **Narrative** | Story arcs and cognitive state | Generated during dreaming cycle |
121118

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.
123120

124121
## Scheduled Tasks
125122

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:
127124

128125
| Task | Cadence | Purpose |
129126
|------|---------|---------|
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.
139167

140168
## Optional Integrations
141169

142170
| Integration | Secret | Purpose |
143171
|-------------|--------|---------|
144172
| GitHub | `GITHUB_TOKEN` | Repository scanning, issue management, self-improvement |
145173
| 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 |
147176
| Memory Worker | Service Binding | Persistent semantic memory with vector search |
148177
| TarotScript | Service Binding | Deterministic symbolic reasoning |
149178

150179
## Tech Stack
151180

152181
- **Runtime**: Cloudflare Workers (V8 isolates, global edge)
153182
- **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)
155184
- **Framework**: Hono (lightweight, edge-native HTTP)
156185
- **Language**: TypeScript (strict mode)
157186
- **Protocol**: MCP (Model Context Protocol)
187+
- **Cost**: $0/month hosting (Workers free tier)
158188

159189
## Live Example
160190

161191
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.
162192

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+
163202
## Documentation
164203

165204
- [Getting Started](docs/getting-started.md) — Deploy your own instance in 5 minutes

0 commit comments

Comments
 (0)