Introduction to Cogmo
Relevant source files
The following files were used as context for generating this wiki page:
Cogmo is a self-hosted personal agent runtime designed for single technical users. It features persistent memory, a Telegram interface, and an evolving prompt system that learns from every conversation. Unlike multi-tenant SaaS platforms, Cogmo is built to run on infrastructure controlled by the user, orchestrating an agentic loop using raw Anthropic and OpenAI SDKs without a heavy framework.
Sources: README.md:12-16, CLAUDE.md:85-93
The system is modular, utilizing PostgreSQL with pgvector for storage, Redis for queuing, and Inngest for durable orchestration. It emphasizes self-evolution through a post-conversation observer that extracts behavioral corrections into steering rules.
Sources: README.md:18-20, README.md:22-26
Architecture Overview
Cogmo's architecture is based on a modular system where infrastructure concerns are strictly separated from domain logic. The core of the system is a long-running Node.js process that connects various adapters and services.
Core Component Map
The following diagram illustrates the relationship between the main components of the Cogmo runtime:
Note: This diagram shows the high-level flow from user interaction to the backend agentic services.
Sources: README.md:12-20, CLAUDE.md:104-124, design/integrations/mcp.md:52-65
Module Responsibilities
| Module | Responsibility | Key Technologies |
|---|---|---|
src/agent/ | Domain logic, tool registry, prompt assembly, and agentic loop. | Anthropic SDK, OpenAI SDK |
src/transport/ | Channel adapters (Telegram, Direct), session management. | grammY |
src/llm/ | Multi-provider abstraction and SDK adapters. | Anthropic, OpenAI, OpenRouter |
src/memory/ | Hindsight adapter for vector memory access. | Hindsight (HTTP) |
src/inngest/ | Durable execution and event-driven orchestration. | Inngest |
Sources: CLAUDE.md:104-124, README.md:32-34
Data and State Management
Cogmo utilizes a variety of storage backends to maintain persistent state and ensure reliable execution.
Storage Infrastructure
- PostgreSQL 18 (with pgvector): Stores application state, secrets, and vector embeddings (via Hindsight). Native UUIDv7 support is recommended for performance.
- Redis 7+: Used by Inngest for managing queues and state stores.
- Local Filesystem: Manages git repositories for skills, cached clones, and ephemeral worktrees under
/var/lib/cogmo.
Sources: README.md:30-34, DEPLOYMENT.md:8-15, DEPLOYMENT.md:46-55
Secrets and Security
Credentials such as API keys and bot tokens are never stored in environment variables or on disk. Instead, they are stored encrypted in the database using AES-256-GCM, with keys derived via HKDF from a COGMO_MASTER_KEY.
Note: This flow shows how secrets are secured before being persisted to the database.
Sources: README.md:65-67, DEPLOYMENT.md:100-104, src/setup/wizard.ts:1095-1100
Integration and Extensibility
Cogmo is designed for pluggability, supporting various communication channels and external tools through the Model Context Protocol (MCP) and a native Skill Library.
Model Context Protocol (MCP)
MCP allows Cogmo to integrate with third-party servers (e.g., GitHub, Gmail, Slack) to expose their tools to the agent.
- Trust Model: Servers are categorized as "trusted" or "untrusted". Untrusted servers are run in a sysbox-runc sandbox with restricted network access.
- Tool Pinning: Cogmo uses SHA256 hashing to pin tool schemas, defending against "schema rug-pull" attacks where a tool's parameters change unexpectedly.
Sources: design/integrations/mcp.md:15-25, design/integrations/mcp.md:144-155, design/integrations/mcp.md:191-205
Skill Library and Self-Evolution
The system features a multi-tiered Skill Library. Skills are written in code and indexed via retrieval keys (descriptions).
| Tier | Metadata | Content | Execution Mode |
|---|---|---|---|
| Tier 1 | Name/Desc | ~50 tokens | Always loaded in tool list |
| Tier 2 | Instructions | ~500 tokens | Loaded on trigger |
| Tier 3 | Assets/Code | Variable | Executed on demand |
Sources: design/integrations.md:38-55
Deployment and Setup
Cogmo is distributed as a single Docker image (ghcr.io/iskhakovt/cogmo).
Guided Setup Wizard
The cogmo setup command initiates an interactive TUI (using @clack/prompts) that:
- Validates LLM provider keys against live APIs.
- Configures Telegram bot tokens and allowlists.
- Probes Hindsight and Inngest reachability.
- Seeds default user profiles and steering rules.
Sources: README.md:46-60, src/setup/wizard.ts:1095-1120
Environment Configuration
Key environment variables required for deployment include:
| Variable | Requirement | Purpose |
|---|---|---|
DATABASE_URL | Required | Postgres connection string |
COGMO_MASTER_KEY | Required | 32-byte base64 key for encryption |
HINDSIGHT_URL | Required | Memory server endpoint |
INNGEST_BASE_URL | Required | Orchestration server endpoint |
OTEL_EXPORTER_OTLP_ENDPOINT | Optional | Enables OpenTelemetry observability |
Sources: DEPLOYMENT.md:100-112, DEPLOYMENT.md:215-220
Summary
Cogmo provides a robust, self-hosted framework for running personalized AI agents. By combining durable orchestration via Inngest, persistent memory through Hindsight, and a secure, sandboxed tool execution environment, it allows technical users to maintain complete control over their assistant's data and capabilities. The project emphasizes a "modular first" architecture, facilitating long-term evolution and community-driven extensibility.