Architecture

System Overview#

Cognest uses an event-driven, plugin-based architecture. At its core, three subsystems work together: the Integration Layer (I/O), the Think Engine (reasoning), and the Skills Runtime (execution).

architecture-overview

// High-level architecture
┌─────────────────────────────────────────────┐
│                Event Bus                     │
├─────────┬──────────────┬────────────────────┤
│         │              │                    │
│  Integrations    Think Engine        Skills  │
│  (WhatsApp,      (LLM-powered       (Custom │
│   Slack,          reasoning &         logic  │
│   Gmail...)       routing)           units)  │
│         │              │                    │
├─────────┴──────────────┴────────────────────┤
│            Credential Store                  │
│            State Manager                     │
│            Config Loader                     │
└─────────────────────────────────────────────┘

Event Flow#

Every interaction follows the same event flow, regardless of which integration triggers it:

Ingest — An integration receives an external event (message, webhook, API call) and normalizes it into an Cognest event.
Dispatch — The Event Bus routes the event to the Think Engine and any registered event handlers.
Reason — The Think Engine evaluates the event against available skills, conversation context, and configured rules.
Execute — Selected skills run in the Skills Runtime, with access to integration APIs and shared state.
Respond — Results flow back through the originating integration to the end user.

lifecycle.ts

import { Cognest } from '@cognest/sdk'

const cognest = new Cognest()

// Listen to the full event lifecycle
cognest.events.on('event:received', (event) => {
  console.log(`[${event.integration}] Received: ${event.type}`)
})

cognest.events.on('think:start', (context) => {
  console.log(`Think Engine processing with ${context.skills.length} available skills`)
})

cognest.events.on('skill:execute', (skill, input) => {
  console.log(`Executing skill: ${skill.name}`)
})

cognest.events.on('response:sent', (response) => {
  console.log(`Response sent via ${response.integration}`)
})

The Think Engine is the reasoning layer that decides how to handle each event. It uses your configured LLM provider (OpenAI, Anthropic, or local models) to analyze incoming messages, select appropriate skills, and compose responses.

cognest.config.yaml

# cognest.config.yaml
engine:
  provider: openai
  model: gpt-4o
  temperature: 0.7
  max_tokens: 2048
  system_prompt: |
    You are a helpful assistant for Acme Corp.
    Use available skills to help users with their requests.
    Always be professional and concise.
  context:
    max_history: 20
    include_metadata: true

Integration Layer#

Integrations are bidirectional connectors that normalize platform-specific protocols into a unified event format. Each integration implements the IntegrationProvider interface.

types.ts

// Integration provider interface
interface IntegrationProvider {
  name: string
  version: string

  // Lifecycle
  initialize(config: IntegrationConfig): Promise<void>
  shutdown(): Promise<void>

  // Inbound
  handleWebhook(req: WebhookRequest): Promise<CognestEvent>

  // Outbound
  send(target: string, message: Message): Promise<SendResult>

  // Capabilities
  capabilities(): IntegrationCapabilities
}

Skills Runtime#

Skills run in an isolated runtime with controlled access to integrations, state, and external APIs. The runtime handles dependency injection, error boundaries, and execution timeouts.

skills/email-triage.ts

import { defineSkill } from '@cognest/sdk'

export default defineSkill({
  name: 'email-triage',
  description: 'Automatically categorize and prioritize incoming emails',

  // Skills declare which integrations they need
  integrations: ['gmail'],

  // Skills declare which permissions they require
  permissions: ['gmail.read', 'gmail.label'],

  async execute(context) {
    const gmail = context.integration('gmail')
    const emails = await gmail.getUnread({ limit: 10 })

    for (const email of emails) {
      const priority = await context.think(
        `Categorize this email as urgent, normal, or low: ${email.subject}`
      )
      await gmail.addLabel(email.id, priority)
    }

    return { processed: emails.length }
  },
})

State Management#

Cognest provides a built-in state manager for persisting conversation context, user preferences, and skill data across sessions. State is automatically scoped per user and per integration.

state-example.ts

// Read and write state within a skill
const prefs = await context.state.get('user-preferences')
await context.state.set('user-preferences', {
  ...prefs,
  timezone: 'America/New_York',
  language: 'en',
})

// State is scoped: state.get() in a WhatsApp context
// returns different data than in a Slack context

System Overview#

Event Flow#

The Think Engine#

Integration Layer#

Skills Runtime#

State Management#