Cogitator AI

Cogitator

AI agents that actually do things.

[](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.npmjs.com/package/@cogitator-ai/core)

[Quick Start](#-quick-start) · [Examples](./examples) · Docs · Discord

---

What is Cogitator?

You know how ChatGPT and Claude are great at talking? Cogitator makes AI that can do things.

An agent is an AI that has tools - it can search the web, read files, call APIs, write code, run queries. You give it a goal, it figures out which tools to use and in what order.

Cogitator is a TypeScript framework for building these agents. One agent or a hundred, local model or cloud API, simple script or production service - same code, same patterns.

import { Cogitator, Agent, tool } from '@cogitator-ai/core';
import { z } from 'zod';

const weather = tool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `${city}: 22°C, sunny`,
});

const agent = new Agent({
  name: 'assistant',
  model: 'google/gemini-2.5-flash', // free tier, no credit card
  instructions: 'You help people with questions. Use tools when needed.',
  tools: [weather],
});

const cog = new Cogitator({
  llm: {
    providers: {
      google: { apiKey: process.env.GOOGLE_API_KEY! },
    },
  },
});
const result = await cog.run(agent, { input: 'What is the weather in Tokyo?' });
console.log(result.output);

That's it. The agent reads your question, decides to call get_weather, gets the result, and writes a human-friendly response.

---

Quick Start

Option A - scaffold a project:

npx create-cogitator-app my-agents
cd my-agents && pnpm dev

Choose from 6 templates: basic agent, agent with memory, multi-agent swarm, DAG workflow, REST API server, or Next.js chat app.

Option B - add to existing project:

pnpm add @cogitator-ai/core zod

Set GOOGLE_API_KEY in your .env (get one free here) and run any [example](./examples):

npx tsx examples/core/01-basic-agent.ts

> Works with any LLM: swap google/gemini-2.5-flash for openai/gpt-4o, anthropic/claude-sonnet-4-6, ollama/llama3.3, or 10+ other providers.

---

Personal AI Assistant

Build your own AI that runs 24/7 on Telegram, Discord, or Slack. No code required — just a YAML config.

cogitator wizard

The interactive wizard walks you through everything: LLM provider, model, channels, capabilities, memory, MCP servers. It generates a cogitator.yml:

name: Jarvis
personality: 'You are Jarvis, a sharp personal assistant.'
llm:
  provider: google
  model: gemini-2.5-flash
channels:
  telegram:
    ownerIds: ['YOUR_TG_ID']
capabilities:
  webSearch: true
  fileSystem:
    paths: [~/Documents, ~/Projects]
  scheduler: true
  browser: true
memory:
  adapter: sqlite
  path: ~/.cogitator/memory.db
  compaction:
    threshold: 50
stream:
  flushInterval: 600
  minChunkSize: 30

The wizard asks your name, picks channels, configures capabilities, and writes everything to cogitator.yml + .env. Then start it:

cogitator up                    # foreground with live dashboard
cogitator daemon start          # background with auto-restart
cogitator daemon install        # register as system service (systemd/launchd)

> You can also use cogitator init to scaffold a full project with package.json, TypeScript config, and source files if you prefer the programmatic API over YAML.

Manage everything from chat — no web dashboard needed:

| Command | What it does | | ----------------- | ------------------------------ | | /status | Uptime, sessions, cost | | /model gpt-4o | Switch model on the fly | | /pair ABC123 | Approve a new user | | /block @spammer | Block a user | | /compact | Compress conversation history | | /cost | Token usage and cost breakdown | | /skills | List installed skills | | /help | All available commands |

What you get out of the box:

• Multi-channel — same assistant on Telegram + Discord + Slack + WhatsApp simultaneously
• Streaming — real-time typing with chunked message editing
• Voice messages — automatic STT via Deepgram, Groq, OpenAI, or local Whisper
• Image understanding — photos sent to the bot are analyzed via vision
• Access control — owner/authorized/public levels, pairing codes for new users
• Scheduled tasks — "remind me in 2 hours" with cron/interval/one-shot support
• Memory — persistent conversations with auto-compaction and knowledge graphs
• Lifecycle hooks — 10 event points for logging, analytics, custom behavior
• Skills — extend with tool bundles (cogitator skill add)
• MCP servers — connect any Model Context Protocol tool server

See [@cogitator-ai/channels README](./packages/channels/README.md) for the full programmatic API and [@cogitator-ai/cli](./packages/cli/) for all CLI commands.

---

What Can You Build?

| Use Case | What happens | Try it | | ---------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Chatbot with memory | Agent remembers your name, preferences, past conversations | [examples/memory/01-basic-memory.ts](./examples/memory/01-basic-memory.ts) | | Research assistant | Agent uses tools, reasons step by step, returns structured answers | [examples/core/01-basic-agent.ts](./examples/core/01-basic-agent.ts) | | Content pipeline | Researcher → Writer → Editor, each agent builds on the previous | [examples/swarms/02-pipeline-swarm.ts](./examples/swarms/02-pipeline-swarm.ts) | | Dev team simulation | Manager delegates frontend/backend to specialists, synthesizes results | [examples/swarms/03-hierarchical-swarm.ts](./examples/swarms/03-hierarchical-swarm.ts) | | REST API server | Mount agents as HTTP endpoints with Swagger, SSE streaming, WebSocket | [examples/integrations/01-express-server.ts](./examples/integrations/01-express-server.ts) | | Data processing workflow | Analyze documents in parallel, aggregate with map-reduce | [examples/workflows/03-map-reduce.ts](./examples/workflows/03-map-reduce.ts) | | Knowledge graph | Extract entities from text, build a graph, traverse relationships | [examples/memory/04-knowledge-graph.ts](./examples/memory/04-knowledge-graph.ts) | | RAG Q&A system | Load docs, chunk, embed, retrieve relevant context, answer questions | [examples/rag/01-basic-retrieval.ts](./examples/rag/01-basic-retrieval.ts) | | Agent evaluation | Measure accuracy, compare models, run A/B tests with LLM judges | [examples/evals/01-basic-eval.ts](./examples/evals/01-basic-eval.ts) | | Personal AI assistant | Your own AI running 24/7 on Telegram, Discord, Slack — manage via chat commands | [cogitator.yml config](#-personal-ai-assistant) | | Cross-framework agents | Expose your agent via Google's A2A protocol, consume external agents | [examples/a2a/01-a2a-server.ts](./examples/a2a/01-a2a-server.ts) |

---

Packages

Install only what you need. Everything is a separate npm package.

| Package | What it does | Example | | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | @cogitator-ai/core | Agents, tools, LLM backends, streaming, everything you need to start | [13 core examples](./examples/core/) | | @cogitator-ai/memory | Your agents remember things. Redis, Postgres, SQLite, MongoDB, Qdrant, in-memory | [4 memory examples](./examples/memory/) | | @cogitator-ai/models | Dynamic model registry with pricing, capabilities, provider metadata | [model registry example](./examples/core/13-model-registry.ts) | | @cogitator-ai/swarms | 7 swarm strategies — hierarchy, round-robin, consensus, pipeline, debate, auction, negotiation | [4 swarm examples](./examples/swarms/) | | @cogitator-ai/workflows | DAG workflows with branching, human approval gates, map-reduce | [3 workflow examples](./examples/workflows/) | | @cogitator-ai/a2a | Google's Agent-to-Agent protocol - expose agents as services, consume external ones | [2 a2a examples](./examples/a2a/) | | @cogitator-ai/mcp | Connect to any MCP server and use its tools | [1 mcp example](./examples/mcp/) | | @cogitator-ai/sandbox | Run untrusted code in Docker or WASM. Never on your host | [sandbox example](./examples/infrastructure/05-sandbox-execution.ts) | | @cogitator-ai/wasm-tools | 14 pre-built tools running in WASM sandbox (calc, json, hash, csv, markdown...) | [wasm example](./examples/advanced/03-wasm-tools.ts) | | @cogitator-ai/self-modifying | Agents that generate new tools at runtime and evolve their own architecture | [self-modifying example](./examples/advanced/01-self-modifying.ts) | | @cogitator-ai/neuro-symbolic | Prolog-style logic, constraint solving, knowledge graphs for agents | [neuro-symbolic example](./examples/advanced/02-neuro-symbolic.ts) | | @cogitator-ai/rag | RAG pipeline - document loaders, chunking, retrieval, reranking | [3 rag examples](./examples/rag/) | | @cogitator-ai/evals | Evaluation framework - metrics, LLM judges, A/B testing, assertions | [3 eval examples](./examples/evals/) | | @cogitator-ai/voice | Voice/Realtime agent capabilities - STT, TTS, VAD, realtime sessions | [3 voice examples](./examples/voice/) | | @cogitator-ai/browser | Browser automation - Playwright, stealth, vision, network control | [4 browser examples](./examples/browser/) | | @cogitator-ai/deploy | Deploy your agents to Docker or Fly.io | [deploy example](./examples/infrastructure/04-deploy-docker.ts) | | @cogitator-ai/channels | Personal AI assistant on Telegram, Discord, Slack, WhatsApp — streaming, commands, media, hooks | [3 channel examples](./examples/channels/) | | @cogitator-ai/cli | cogitator init / up / daemon / skill / deploy from your terminal | - |

Server adapters - mount agents as REST APIs with one line:

express · fastify · hono · koa · next · ai-sdk · openai-compat

All with Swagger docs, SSE streaming, and WebSocket support. See [integration examples](./examples/integrations/).

---

Features at a Glance

LLM & Models

| Feature | What it means | | ---------------------- | ------------------------------------------------------------------------------------------------ | | Any provider | OpenAI, Anthropic, Google, Ollama, Azure, Bedrock, Mistral, Groq, Together, DeepSeek - same code | | Structured outputs | JSON mode and JSON Schema validation across all providers | | Vision & audio | Send images, transcribe audio, generate speech | | Cost-aware routing | Auto-pick cheap models for easy tasks, expensive for hard ones | | Cost prediction | Know how much a run will cost before you execute it |

Memory & Knowledge

| Feature | What it means | | ---------------------- | ---------------------------------------------------------------- | | 6 storage backends | Redis, Postgres, SQLite, MongoDB, Qdrant, in-memory | | Semantic search | BM25 + vector hybrid search with Reciprocal Rank Fusion | | Knowledge graphs | Extract entities, build graphs, traverse multi-hop relationships | | RAG pipeline | Document loaders, smart chunking, hybrid retrieval, reranking | | Context management | Auto-compress long conversations to fit model limits |

Multi-Agent

| Feature | What it means | | ---------------------- | ---------------------------------------------------------------------------- | | 7 swarm strategies | Hierarchical, consensus, round-robin, auction, pipeline, debate, negotiation |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cogitator-ai
• Source: cogitator-ai/Cogitator-AI
• License: MIT
• Homepage: https://cogitator.app

Install and usage instructions live in the source repository linked above.