Khurram Badar / Archive / Papers / Createagent Runtime — Architecture Document

Createagent Runtime — Architecture Document

briefing · 2026-04-22 · 1747 words · Khurram Badar

1. The Thesis 2.

ai · education · technology

Createagent Runtime — Architecture Document

**Author:** Khurram Badar
**Stack target:** Next.js (Vercel) + Supabase + Anthropic Claude API
**Inspiration:** Nous Research's Hermes Agent
**Status:** Blueprint v1 — ready to hand to Claude Code

---

1. The Thesis

Today, every "agent" built on createagent.ai is a stateless prompt with an API endpoint — describe it, deploy it, call it. That's good enough for demos. It is not good enough to be a category-defining platform.

The Createagent Runtime turns each user-built agent into a **persistent, learning entity**. Every conversation adds to the agent's memory. Every successful task can become a reusable skill. The agent gets noticeably smarter the longer the user uses it. That is the moat — competitors deploying flat prompts cannot catch up to an agent that has a year of accumulated context with its user.

Hermes proved this works as a self-hosted CLI. Createagent Runtime ports the same architecture into a hosted, multi-tenant SaaS that non-technical founders can spin up in minutes.

---

2. Architectural Pillars

Five pillars, each lifted from Hermes and adapted for a SaaS context:

1. **Skills** — versioned, on-demand knowledge documents the agent loads only when needed.
2. **Bounded curated memory** — two tiny self-managed files per agent: AGENT_MEMORY and USER_MEMORY.
3. **Cross-session recall** — Postgres full-text search over the agent's entire conversation history.
4. **Multi-channel gateway** — same agent reachable via web chat, Telegram, WhatsApp, email, embed widget.
5. **Sandboxed tool execution** — code/tool calls run in an isolated environment, never on your Vercel functions.

Everything else is plumbing.

---

3. Data Model (Supabase / Postgres)

Add these tables to your existing `createagent` schema. Names assume one row per agent (you already have `agents`).

`agent_skills`

`agent_memory`

`agent_sessions`

`agent_messages`

Index: `CREATE INDEX agent_messages_search_idx ON agent_messages USING gin(search_vector);`

`agent_skill_extractions`

---

4. Prompt Assembly (the heart of the runtime)

On every turn, the runtime assembles the prompt in this order. Aim for ~6–8K tokens before the conversation itself.

```
[SYSTEM]
+ Agent identity and role (from agents.system_prompt)
+ AGENT_MEMORY.md (max 2200 chars)
+ USER_MEMORY.md for this end-user (max 1375 chars)
+ Skill index — Level 0 (name + 1-line description for each skill, ~3000 tokens cap)
+ Tool definitions (only enabled tools)

[CONVERSATION]
+ Last N turns of the current session (default 20)
+ Optional: top-3 retrieved past-message snippets if the user references something old

[USER]
+ The new message
```

Key tools the agent always has access to:

Plus whatever user-enabled tools (web search, Gmail/Calendar via MCP, custom HTTP endpoints, etc.).

---

5. Background Workers

Three background jobs run on every session close (or on a schedule). Use Supabase Edge Functions or a small Vercel cron + Inngest setup.

5.1 Memory Janitor

> *"You are the memory keeper for an AI agent. Here is the current AGENT_MEMORY.md (max 2200 chars) and USER_MEMORY.md (max 1375 chars). Here is a transcript of the session that just ended. Output the updated versions of both files. Do not exceed the character limits. Replace stale entries, consolidate duplicates, add new lessons."*

Writes back to `agent_memory`.

5.2 Session Summarizer

5.3 Skill Extractor

> *"Review this conversation. Did the assistant solve a non-trivial, repeatable task? If yes, write a SKILL.md document with: a name (snake_case), a one-line description, YAML frontmatter (when_to_use, tools_required), and a procedural body. If no, output 'REJECT'."*

If extracted, save to `agent_skills` and mark the queue row 'extracted'.

---

6. The Gateway (multi-channel)

A single Node service (deploy on Railway, Fly, or a small VPS — not Vercel, you need long-running connections).

It does three things:
1. Holds connections to messaging platforms (Telegram bot, WhatsApp via Twilio, email via Postmark inbound webhooks).
2. Translates inbound messages to Createagent's standard message envelope.
3. Calls the agent runtime API and routes the response back to the originating channel.

Start with web chat (already in your app) + Telegram. Telegram's Bot API is the cleanest of all of them — a single long-poll loop and you're live in a day.

Each user-built agent gets its own gateway routing config, stored in `agents.gateway_config` jsonb. Example:

```json
{
"telegram": { "bot_token": "<encrypted>", "enabled": true },
"whatsapp": { "twilio_number": "+971...", "enabled": false },
"email": { "inbound_address": "agentname@createagent.ai" }
}
```

Encryption: use Supabase Vault for tokens.

---

7. Sandboxed Tool Execution

Never run user-defined tools or arbitrary code on your Vercel functions — one bad agent crashes the platform.

Recommendation: use **Modal** or **E2B**. Both expose serverless Python sandboxes via API. Modal has the better hibernation story (Hermes uses it for the same reason); E2B is purpose-built for agent code execution.

Pattern: when the agent calls a code-execution tool, the runtime POSTs the code + context to the sandbox provider, gets back stdout/stderr/files, and returns it to the model as a tool result. Per-agent sandboxes get reused for ~15 minutes then hibernate.

For network tools (web search, HTTP fetches), proxy through a single hardened endpoint with rate limiting per agent.

---

8. MCP Support

Adopt MCP as the standard tool protocol. Users paste an MCP server URL into their agent settings (Gmail, Calendar, Drive, Slack, GitHub, Notion, Asana — most major SaaS now have MCP servers). Your runtime adds those tools to the agent's available tool list dynamically per session.

This single feature gives every Createagent user instant integration with hundreds of services without you writing a single integration. It is the cheapest moat-builder on this list.

---

9. Build Sequence (3 phases)

Phase 1 — Memory + Skills (Week 1)

Phase 2 — Recall + Extraction (Week 2)

Phase 3 — Gateway + Sandbox + MCP (Week 3–4)

Phase 4 — Marketplace (Month 2)

---

10. First Three Prompts to Hand Claude Code

Copy-paste these in order into Claude Code from `~/projects/createagent`:

**Prompt 1:**
> Read CLAUDE.md. Then read this architecture doc at /home/khurramb/Downloads/CREATEAGENT_RUNTIME_ARCHITECTURE.md. Add the four new Supabase tables (agent_skills, agent_memory, agent_sessions, agent_messages) as a new migration. Don't touch existing tables. Generate the migration file, run it locally against Supabase, and confirm the schema matches the doc.

**Prompt 2:**
> Refactor the agent runtime in /app/api/agents/[id]/chat/route.ts to assemble the prompt as described in section 4 of the architecture doc. Pull AGENT_MEMORY and USER_MEMORY from agent_memory. Build the Level-0 skill index from agent_skills. Add the load_skill and update_memory tools. Write tests that confirm the assembled prompt structure.

**Prompt 3:**
> Build the Memory Janitor as a Supabase Edge Function. Trigger: a new row in agent_sessions with last_message_at older than 5 minutes. Use the prompt from section 5.1 of the architecture doc. Update agent_memory in place. Add a unit test using a sample transcript.

After Phase 1 ships, write Prompts 4–6 for Phase 2.

---

11. Pricing Implication

The runtime fundamentally changes your cost structure: each agent now uses meaningfully more tokens per call (memory + skill index added to system prompt). Two responses:

The persistent-agent capability is the upsell hook. Free users feel the difference instantly when they upgrade — their agent finally remembers them.

---

12. What This Doc Deliberately Skips

Because they're not core to the runtime:

---

13. Open Questions for You

1. Do you want to support self-hosted Createagent (BYO API key + open-source runtime), or stay pure SaaS?
2. Pricing: rev-share with skill marketplace authors, or flat marketplace fee?
3. Branding: position Createagent Runtime as a separate product, or a feature called "Persistent Mode" inside today's product?

Answers to these shape Phase 4 and beyond. Phases 1–3 don't depend on them.

← 14. Vertical Agent Pack #2 — The Routine AgentPhase 2 — Post-Signing Autonomy Stack →
Two years of working thought, indexed.
Ask me to present it in your conference room — WhatsApp +971 55 623 9111
Book Session →