Architecture

HeyCMO is built on the Mastra AI framework with a layered architecture designed for reliability, memory persistence, and multi-agent orchestration.

Tech Stack

System Diagram

┌─────────────────────────────────────────────────────────┐
│                     Hono HTTP Server                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
│  │ /mcp/sse │  │/api/health│  │/api/innge│  │/api/*  │  │
│  │/mcp/msg  │  │/api/h/rdy │  │  st      │  │billing │  │
│  └────┬─────┘  └──────────┘  └────┬─────┘  └───┬────┘  │
│       │                            │             │       │
│  ┌────▼────────────────────────────▼─────────────▼───┐  │
│  │              Mastra AI Framework                   │  │
│  │  ┌──────────────────────────────────────────────┐  │  │
│  │  │              Agent Layer (17 agents)          │  │  │
│  │  │  CMO → SEO Writer, Social, Email, Analyst,   │  │  │
│  │  │  Engagement, Researcher, CRO, Growth, Sales  │  │  │
│  │  └──────────────────┬───────────────────────────┘  │  │
│  │                     │                               │  │
│  │  ┌─────────┐  ┌────▼────┐  ┌────────────────────┐  │  │
│  │  │  Tools  │  │Workflows│  │  Memory (4-layer)  │  │  │
│  │  │  (15+)  │  │  (12)   │  │  Working│Semantic  │  │  │
│  │  └─────────┘  └─────────┘  │  Episodic│Procedural│  │  │
│  │                             └────────────────────┘  │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │PostgreSQL│  │ Inngest  │  │ Stripe   │  │ Composio │  │
│  │ + pgvec  │  │Cron/Queue│  │ Billing  │  │   MCP    │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────┘

4-Layer Memory System

HeyCMO agents have persistent, contextual memory across all interactions:

Working Memory

Short-term context for the current conversation. Stores brand profile, recent instructions, and active task context. Every agent reads brand context from working memory before making decisions.

Semantic Memory (RAG)

Long-term knowledge stored as vector embeddings in PostgreSQL with pgvector. Past content, research findings, and brand guidelines are chunked, embedded with OpenAI's text-embedding-3-small, and retrievable via similarity search.

• Content Query Tool — Agents search past content for reference and inspiration
• Performance Query Tool — Agents query historical performance data for data-driven decisions

Episodic Memory

Records of past agent interactions and outcomes. Enables agents to learn from previous successes and failures — "last time we wrote about this topic, it scored 0.85 on brand voice."

Procedural Memory

Self-optimization loop that adjusts agent behavior based on patterns. The Self-Optimization Workflow analyzes telemetry data, detects patterns (declining quality, improving engagement), and proposes weight adjustments to scoring criteria.

Human-in-the-Loop Approval

HeyCMO uses a suspend/resume workflow pattern for human approval. When the content creation workflow produces content:

1. Content is scored by the eval system (brand voice, quality, engagement prediction)
2. The workflow suspends and waits for human approval
3. You review the content via list_pending_approvals in your MCP client
4. You call resume_workflow with an approve or reject decision
5. Approved content proceeds to publishing; rejected content goes back for revision

This ensures nothing publishes without your explicit approval while keeping the automation pipeline fully intact.

Inngest Cron Jobs

HeyCMO uses Inngest for durable, scheduled workflow execution:

• Daily Research — Automated content research runs on a schedule
• Engagement Monitoring — Periodic checks for comments and DMs across platforms
• Self-Optimization — Regular performance analysis and strategy adjustment
• Events Cleanup — Periodic cleanup of stale event data

Inngest provides automatic retries, crash recovery, and observability for all scheduled functions. The /api/inngest endpoint serves as the function handler.

Real-Time Progress Events

Long-running workflows (like the research pipeline) emit real-time progress notifications via the MCP protocol:

Step 1/6: Analyzing brand context...
Step 2/6: Searching web sources via Exa...
Step 3/6: Extracting social signals from X/Twitter...
Step 4/6: Scoring and ranking ideas...
Step 5/6: Identifying SEO quick wins...
Step 6/6: Storing results in semantic memory...

Progress events are forwarded to your MCP client as notifications/progress messages, giving you live visibility into what HeyCMO is doing.

Workflow Recovery

On server restart, HeyCMO automatically recovers interrupted workflows from PostgresStore. The recovery system checks for running or suspended workflow runs and restarts them, ensuring research pipelines and other long-running workflows survive server restarts without data loss.

Recoverable workflows: researchPipeline, contentCreation, crossChannelPublish, brandInterview, engagementResponse, analyticsReport, selfOptimization.

Agent Safety Processors

Every agent has input and output processors for safety:

Eval System

Before any content is presented for approval, it passes through three evaluation dimensions:

1. Brand Voice Match — Compares generated content against the brand profile for tone, vocabulary, and style consistency (0–1 score)
2. Content Quality — Evaluates structure, depth, readability, and SEO optimization (0–1 score)
3. Engagement Prediction — Predicts likely engagement based on historical performance patterns (0–1 score)

Content scoring below configurable thresholds is flagged for revision before human review.

Infrastructure

Rate Limiting

Per-key and per-IP rate limiting with configurable burst rates per endpoint category (API, MCP, checkout, webhooks, admin).

Authentication

API keys use the hcmo_live_ prefix, are hashed with SHA-256 for storage, and validated with timing-safe comparison. MCP endpoints use token-based auth via query parameter.

CORS & Security Headers

Strict CORS policy (only heycmo.ai and app.heycmo.ai), plus X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, and Strict-Transport-Security headers on all responses.

Body Size Limits

Request body size is enforced per endpoint: 100KB for API routes, 1MB for Stripe webhooks, 10KB for admin routes.

SSRF Protection

All URL-accepting tools validate against private/internal IP ranges (localhost, 10.x, 172.16-31.x, 192.168.x, link-local, AWS metadata endpoint) to prevent server-side request forgery.