Glossary & Core Concepts
Relevant source files
The following files were used as context for generating this wiki page:
Cogmo is a self-hosted personal agent runtime designed with a modular architecture, persistent memory, and a focus on self-evolution. It is built for technical users to control their own assistant on their own infrastructure, integrating various LLM providers, external tools via the Model Context Protocol (MCP), and a robust memory system called Hindsight.
The project follows a "Single technical user" philosophy, prioritizing control and privacy over multi-tenant SaaS features. The core logic revolves around an agentic loop that processes messages, interacts with tools, and utilizes memory networks to improve behavior over time.
Sources: CLAUDE.md:3-5, README.md:16-20
Core Entities & Concepts
Agent & Orchestrator
The Agent represents the domain logic of how Cogmo thinks and acts, including the agentic loop, tool registry, and prompt assembly. The Orchestrator (often implemented via Inngest) handles the durable execution of message handling, event-driven task management, and crash recovery.
Sources: CLAUDE.md:73-74, CLAUDE.md:129-131
Service & Tool
A Service provides a scoped interface for tools to access external systems (e.g., memory, web, files). Tools are specific functions the agent can execute, which are strictly scoped by the orchestrator to maintain ACL boundaries.
Sources: CLAUDE.md:144-150, design/integrations/mcp.md:52-54
Transport & Channel
Transport defines how messages arrive and are delivered. Channels (like Telegram or Direct) are specific implementations of message interfaces that interact with the user.
Sources: CLAUDE.md:76-78, README.md:20-22
Memory & Hindsight
Cogmo utilizes Hindsight, a self-hosted memory server using PostgreSQL and pgvector. Memory is structured into four networks and includes an Observer component that extracts behavioral corrections into steering rules.
Sources: CLAUDE.md:37-38, README.md:20-22
Component Architecture
The following diagram illustrates the relationship between the user interface, the orchestration layer, and the underlying domain services.
The diagram shows the flow from user input through transport adapters to the Inngest-managed agentic loop.
Sources: CLAUDE.md:43-61, README.md:20-22
Integration & Extensions
Model Context Protocol (MCP)
The MCP integration allows Cogmo to connect to third-party servers (e.g., GitHub, Gmail) to expand its toolset. It treats servers as untrusted by default and uses a connection pool for lazy-connecting to stdio or HTTP transports.
| Concept | Description |
|---|---|
| McpRegistry | Facade consumed by the message handler to resolve tools per turn. |
| Tool Pinning | SHA256 hashing of tool schemas to prevent "rug-pull" attacks. |
| Sandboxing | Using sysbox-runc containers for untrusted stdio servers. |
| SecretRef | Discriminated union allowing config to mix literals and encrypted secrets. |
Sources: design/integrations/mcp.md:19-25, design/integrations/mcp.md:130-145, design/integrations/mcp.md:214-225
Coding Delegation & Sandboxing
Cogmo supports autonomous coding tasks by delegating work to subprocesses like Claude Code or Codex CLI. This system uses a container sandbox for isolation and lineage tracking.
This diagram outlines the security gates and infrastructure used for autonomous coding delegation.
Sources: changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md:1-25
System Setup & Configuration
The Setup Wizard is a TUI-based interactive flow used for first-run configuration. It validates credentials live and stores them encrypted in the database.
Wizard Configuration Steps
- LLM Provider: Selection of Anthropic, OpenAI, or OpenRouter with live API validation.
- Telegram Bot: Configuration of @BotFather tokens and user allowlists.
- Optional Tools: Setup for Tavily (search) and fal.ai (image generation).
- GitHub Identity: SSH keypair generation and PAT storage for coding tasks.
- Voice Config: Setup for TTS (Text-to-Speech) and STT (Speech-to-Text) providers.
Sources: src/setup/wizard.ts:153-170, src/setup/wizard.ts:397-420, src/setup/wizard.ts:742-760
Module Structure
The project maintains strict boundaries between domain logic and infrastructure.
| Module | Responsibility |
|---|---|
src/agent/ | Domain logic: how the agent thinks, tool registry, and prompt assembly. |
src/transport/ | Delivery logic: channel adapters, sessions, and identity. |
src/llm/ | Provider abstraction: translating between Cogmo types and SDK-specific formats. |
src/memory/ | Memory access: HTTP client for the Hindsight server. |
src/inngest/ | Orchestration infra: event definitions and client setup. |
Sources: CLAUDE.md:85-115
Development & Release Lifecycle
Cogmo uses Conventional Commits to drive an automated release process via semantic-release.
- Type check & Lint: Mandatory CI checks before merging.
- Record/Replay: Integration tests use
llmockfixtures to avoid expensive API calls during dev. - Changelog Fragments: Each PR requires a unique Markdown file in
changelog.d/to document changes without merge conflicts.
Sources: CONTRIBUTING.md:13-18, CONTRIBUTING.md:41-45, changelog.d/README.md:1-15
Cogmo's architecture ensures that it remains a durable, self-evolving system suitable for long-term personal use while maintaining high standards for technical accuracy and security.