---

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();
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:

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 for the full programmatic API and @cogitator-ai/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
Research assistant	Agent uses tools, reasons step by step, returns structured answers	examples/core/01-basic-agent.ts
Content pipeline	Researcher → Writer → Editor, each agent builds on the previous	examples/swarms/02-pipeline-swarm.ts
Dev team simulation	Manager delegates frontend/backend to specialists, synthesizes results	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
Data processing workflow	Analyze documents in parallel, aggregate with map-reduce	examples/workflows/03-map-reduce.ts
Knowledge graph	Extract entities from text, build a graph, traverse relationships	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
Agent evaluation	Measure accuracy, compare models, run A/B tests with LLM judges	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
Cross-framework agents	Expose your agent via Google's A2A protocol, consume external agents	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	12 core examples
@cogitator-ai/memory	Your agents remember things. Redis, Postgres, SQLite, MongoDB, Qdrant, in-memory	4 memory examples
@cogitator-ai/swarms	7 swarm strategies — hierarchy, round-robin, consensus, pipeline, debate, auction, negotiation	4 swarm examples
@cogitator-ai/workflows	DAG workflows with branching, human approval gates, map-reduce	3 workflow examples
@cogitator-ai/a2a	Google's Agent-to-Agent protocol - expose agents as services, consume external ones	2 a2a examples
@cogitator-ai/mcp	Connect to any MCP server and use its tools	1 mcp example
@cogitator-ai/sandbox	Run untrusted code in Docker or WASM. Never on your host	sandbox example
@cogitator-ai/wasm-tools	14 pre-built tools running in WASM sandbox (calc, json, hash, csv, markdown...)	wasm example
@cogitator-ai/self-modifying	Agents that generate new tools at runtime and evolve their own architecture	self-modifying example
@cogitator-ai/neuro-symbolic	Prolog-style logic, constraint solving, knowledge graphs for agents	neuro-symbolic example
@cogitator-ai/rag	RAG pipeline - document loaders, chunking, retrieval, reranking	3 rag examples
@cogitator-ai/evals	Evaluation framework - metrics, LLM judges, A/B testing, assertions	3 eval examples
@cogitator-ai/voice	Voice/Realtime agent capabilities - STT, TTS, VAD, realtime sessions	3 voice examples
@cogitator-ai/browser	Browser automation - Playwright, stealth, vision, network control	4 browser examples
@cogitator-ai/deploy	Deploy your agents to Docker or Fly.io	deploy example
@cogitator-ai/channels	Personal AI assistant on Telegram, Discord, Slack, WhatsApp — streaming, commands, media, hooks	3 channel examples
@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.

---

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
DAG workflows	Build pipelines with branching, retries, compensation, human approval
A2A Protocol	Google's standard for agents talking to agents across frameworks
Agent-as-Tool	Use one agent as a tool for another - simple delegation

Messaging Channels

Feature	What it means
5 platforms	Telegram, Discord, Slack, WhatsApp, WebChat — same agent, multiple channels
YAML config + CLI	cogitator.yml + cogitator up — personal assistant without writing code
Gateway routing	Sessions, streaming, middleware, media processing through one unified entry point
Owner commands	Manage your assistant from chat — /status, /model, /block, /cost
Access control	DM policy with 4 modes (open, allowlist, pairing, disabled) + authorization levels
Media processing	Photos → vision, voice → STT (Deepgram, Groq, OpenAI, local Whisper)
Streaming	Real-time message editing with smart chunking and platform-aware splitting
Status reactions	Emoji progress indicators (queued → thinking → tool → done) on user messages
Lifecycle hooks	10 event points for logging, analytics, and custom behavior
Scheduler	Cron, interval, and one-shot jobs with error tracking and auto-backoff
Daemon mode	Run as system service with cogitator daemon install (systemd/launchd)

Safety & Security

Feature	What it means
Constitutional AI	Auto-filter harmful inputs/outputs with critique-revision loops
Prompt injection detection	Catch jailbreaks, DAN attacks, encoding tricks
Sandboxed execution	Docker and WASM isolation for untrusted code
Tool guards	Block dangerous commands, validate paths, require approval

Advanced

Feature	What it means
Self-modifying agents	Agents detect missing capabilities and generate new tools at runtime
Tree of Thoughts	Explore multiple reasoning paths with backtracking
Causal reasoning	Pearl's Ladder - association, intervention, counterfactuals
Self-reflection	Agents learn from their actions and improve over time
Agent optimizer	DSPy-style instruction tuning from execution traces
Time-travel debugging	Checkpoint, replay, fork agent executions like git bisect
Neuro-symbolic	Prolog-style logic + SAT solving for formal reasoning

Developer Experience

Feature	What it means
OpenTelemetry	Full tracing to Jaeger, Grafana, Datadog
Langfuse	LLM-native observability with prompt management
Tool caching	Cache tool results (exact or semantic matching)
Agent serialization	Save agents to JSON, restore later
Debug mode	Full request/response logging for LLM calls
Evals framework	Metrics, LLM judges, A/B testing, assertions
Plugin system	Register custom LLM backends

---

Why Cogitator?

	Cogitator	LangChain	OpenAI Assistants
Language	TypeScript	Python	REST API
Self-hosted	Yes	Yes	No
Any LLM	Yes	Yes	OpenAI only
Multi-agent	7 strategies	Limited	No
A2A Protocol	Yes	No	No
Observability	OpenTelemetry	Requires setup	Dashboard only
Dependencies	~20	150+	N/A

---

55 Runnable Examples

Every major feature has a working example you can run right now.

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

Category	Count	What you'll learn
core/	12	Agents, tools, streaming, caching, tree-of-thought, reflection, optimization, time-travel, cost routing, constitutional AI, prompt injection, causal reasoning
memory/	4	In-memory storage, context building, semantic search, knowledge graphs
swarms/	4	Debate, pipeline, hierarchical coordination, negotiation
workflows/	3	DAG workflows, human-in-the-loop, map-reduce
a2a/	2	A2A server and client
mcp/	1	MCP server integration
rag/	3	Basic retrieval, chunking strategies, agent with RAG
evals/	3	Basic evaluation, LLM judge, A/B comparison
voice/	3	Voice pipeline, realtime sessions, voice agents
browser/	4	Web scraping, form automation, stealth agents, crypto price scraper
integrations/	7	Express, Fastify, Hono, Koa, Next.js, OpenAI compat, AI SDK
infrastructure/	4	Redis, PostgreSQL, job queues, Docker deploy
channels/	3	Telegram assistant, multi-channel super-assistant, WebChat bot
advanced/	3	Self-modifying agents, neuro-symbolic reasoning, WASM tools

Default LLM is Google Gemini 2.5 Flash - free tier, no credit card. See examples/README.md for setup.

---

Contributing

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/cogitator.git
cd cogitator && pnpm install && pnpm dev

See CONTRIBUTING.md for guidelines.

---

All npm packages

Package	Description	Version
@cogitator-ai/core	Core runtime (Agent, Tool, Cogitator)
create-cogitator-app	Interactive project scaffolding (npx create-cogitator-app)
@cogitator-ai/cli	CLI tool (cogitator init/up/run/deploy)
@cogitator-ai/types	Shared TypeScript interfaces
@cogitator-ai/config	Configuration management
@cogitator-ai/memory	Memory adapters (Postgres, Redis, SQLite, MongoDB, Qdrant)
@cogitator-ai/models	Dynamic model registry with pricing
@cogitator-ai/workflows	DAG-based workflow engine
@cogitator-ai/swarms	Multi-agent swarm coordination
@cogitator-ai/mcp	MCP (Model Context Protocol) support
@cogitator-ai/a2a	A2A Protocol v0.3 - cross-agent interoperability
@cogitator-ai/sandbox	Docker/WASM sandboxed execution
@cogitator-ai/redis	Redis client (standalone + cluster)
@cogitator-ai/worker	Distributed job queue (BullMQ)
@cogitator-ai/openai-compat	OpenAI Assistants API compatibility
@cogitator-ai/wasm-tools	WASM-based sandboxed tools (14 built-in)
@cogitator-ai/self-modifying	Self-modifying agents with meta-reasoning
@cogitator-ai/neuro-symbolic	Neuro-symbolic reasoning with SAT/SMT
@cogitator-ai/rag	RAG pipeline with loaders, chunking, retrieval, reranking
@cogitator-ai/evals	Evaluation framework with metrics, A/B testing, assertions
@cogitator-ai/voice	Voice/Realtime agents (STT, TTS, VAD, realtime sessions)
@cogitator-ai/browser	Browser automation (Playwright, stealth, vision, 32 tools)
@cogitator-ai/dashboard	Real-time observability dashboard
@cogitator-ai/next	Next.js App Router integration
@cogitator-ai/ai-sdk	Vercel AI SDK adapter (bidirectional)
@cogitator-ai/express	Express.js REST API server
@cogitator-ai/fastify	Fastify REST API server
@cogitator-ai/hono	Hono multi-runtime server (Edge, Bun, Deno, Node.js)
@cogitator-ai/koa	Koa middleware-based server
@cogitator-ai/deploy	Deployment engine (Docker, Fly.io)

---

Star History

---

License

MIT - see LICENSE.

---