Architecture
How the Cogitator runtime and its packages fit together.
High-Level Architecture
Cogitator is a library-first runtime: everything runs inside your Node.js process (or a worker you start), and every capability is a package you add when you need it.
┌──────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ Your code (SDK) │ Server adapters │ Channel gateway │ CLI │ MCP/A2A │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ COGITATOR RUNTIME (core) │
│ Agent loop · tool execution · approvals · handoffs · retries │
│ guardrails · prompt-injection / PII · cost tracking · tracing │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATION │
│ Workflows (DAG, sagas, timers) │ Swarms (7 strategies) │ Workers │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ STATE & EXECUTION BACKENDS │
│ Memory adapters: in-memory, Redis, Postgres (pgvector), SQLite, │
│ MongoDB, Qdrant │ Workflow run/approval/timer/checkpoint stores │
│ Docker / WASM sandboxes │ BullMQ queues │
└──────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ LLM BACKENDS │
│ Ollama │ OpenAI │ Anthropic │ Google │ Azure │ Bedrock │ vLLM │
│ Mistral │ Groq │ Together │ DeepSeek │ custom backends & plugins │
└──────────────────────────────────────────────────────────────────────┘Packages
The monorepo publishes 32 @cogitator-ai/* packages plus the create-cogitator-app scaffolder (see Project Structure for the full list). Dependencies point downwards:
Foundation
@cogitator-ai/types— shared TypeScript interfaces, error codes and defaults; no dependencies@cogitator-ai/models— model registry with pricing, context windows and capabilities (LiteLLM data with built-in fallbacks)@cogitator-ai/redis— Redis client for standalone and cluster setups@cogitator-ai/config—cogitator.ymland environment loading with Zod validation
Runtime
@cogitator-ai/memory— memory adapters, embeddings, context builder, hybrid search, knowledge graphs@cogitator-ai/core—Cogitator,Agent,tool(), LLM backends, built-in tools; depends ontypes,modelsandmemory
Capabilities
@cogitator-ai/workflows— DAG engine, sagas, map-reduce, human-in-the-loop, timers, scheduling@cogitator-ai/swarms— multi-agent coordination@cogitator-ai/rag— loaders, chunkers, retrieval and reranking@cogitator-ai/sandboxand@cogitator-ai/wasm-tools— isolated code execution and WASM tools@cogitator-ai/browser— Playwright browser automation@cogitator-ai/voice— STT, TTS, VAD and realtime voice agents@cogitator-ai/evals— metrics, datasets, A/B comparison@cogitator-ai/self-modifying,@cogitator-ai/neuro-symbolic— runtime tool generation, logic programming
Protocols, Servers and Channels
@cogitator-ai/mcp,@cogitator-ai/a2a— Model Context Protocol and Agent-to-Agent protocol@cogitator-ai/server-shared— shared REST/SSE/WebSocket protocol and OpenAPI generation@cogitator-ai/express,fastify,hono,koa,tetsu,next— server and framework adapters@cogitator-ai/ai-sdk,@cogitator-ai/openai-compat— Vercel AI SDK bridge, OpenAI Assistants-compatible API@cogitator-ai/channels— Telegram, Discord, Slack, WhatsApp and WebChat gateway
Operations
@cogitator-ai/worker— BullMQ distributed job queue@cogitator-ai/deploy,@cogitator-ai/cli— Docker and Fly.io deployment, thecogitatorcommand@cogitator-ai/test-utils— mocks and helpers for tests
Agent Execution Flow
cogitator.run(agent, { input, threadId, ... })
│
├── Wait for a run slot (limits.maxConcurrentRuns)
├── Resolve the model (agent.model or llm.defaultModel) and its backend
├── Pick versioned instructions / A/B variant (cog.prompts)
├── Build messages: instructions, memory history, facts and semantic context
├── Input checks: prompt injection, guardrails
│
└── Loop (up to maxIterations)
│
├── LLM call (PII masked, retried on rate limits and 5xx)
│
├── Tool calls?
│ ├── validate arguments with the Zod schema
│ ├── requiresApproval → onApproval, or pause the run (status: 'paused')
│ ├── transfer_to_<agent> → hand the conversation over
│ └── execute (natively or in a sandbox), append results, loop
│
└── Final answer → check responseFormat (one repair attempt)
│
▼
Save to memory, record cost and prompt metrics
│
▼
RunResult { output, structured, toolCalls, usage, trace, ... }A paused run continues with cogitator.resume(); see Tool Approvals.
Key Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Language | TypeScript (strict) | Type safety, Node.js ecosystem, full-stack |
| Package manager | pnpm workspaces | Fast, disk-efficient, workspace protocol |
| Task runner | Turborepo | Cached, dependency-ordered builds |
| Module system | ESM | Modern standard, tree-shaking |
| Schema validation | Zod 4 | Runtime + static types from single source |
| Build | tsc (tsup for scaffolder) | Plain emitted ESM with declarations |
Extensibility
Every layer is pluggable:
- LLM backends — implement the
LLMBackendinterface and pass it inllm.backends, or register a plugin withregisterLLMBackend()(LLM Backends) - Memory adapters — implement the
MemoryAdapterinterface - Tools — the
tool()factory wraps any async function;toolset()groups typed tools - Run checkpoints and prompt versions —
runCheckpoints,prompts.versionsandprompts.abTeststake your own stores - Workflow nodes and stores —
functionNode()wraps arbitrary code; run, approval, timer and checkpoint stores have in-memory, Redis and Postgres implementations - Server adapters — build on
@cogitator-ai/server-sharedlike the existing adapters