System Architecture
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 a single technical user. It features a modular architecture built on TypeScript and Node.js, emphasizing persistent memory, event-driven orchestration, and self-evolution. The system is designed to run as a single containerized process that interacts with external infrastructure like PostgreSQL, Redis, and specialized memory servers.
The architecture prioritizes long-term growth through early abstractions, decoupling components via event buses, and maintaining thin infrastructure layers. It avoids heavy frameworks in favor of raw SDKs to maintain control over the agentic loop and its evolutionary capabilities.
Sources: README.md:14-17, CLAUDE.md:1-12, CLAUDE.md:139-158
Core Component Map
The system is divided into domain-specific modules and infrastructure wrappers. Domain logic resides in src/agent/ and src/transport/, while infrastructure setup is isolated in modules like src/db/, src/llm/, and src/memory/.
Component Responsibilities
| Module | Responsibility | Architectural Rule |
|---|---|---|
src/agent/ | Agentic loop, tool registry, prompt assembly, domain logic. | Owns "how" the agent thinks and acts. |
src/transport/ | Channel adapters (Telegram, Direct), session management, delivery routing. | Manages message arrival and delivery. |
src/llm/ | LLM provider abstraction, SDK adapters (Anthropic, OpenAI). | Request/response translation; provider neutral. |
src/memory/ | Memory provider interface, Hindsight HTTP client adapter. | Abstracted memory access. |
src/inngest/ | Event definitions and client setup. | Infrastructure only; no business logic. |
Sources: CLAUDE.md:110-137, design/integrations/mcp.md:50-65
High-Level Topology
The following diagram illustrates the relationship between the core runtime, its internal modules, and the external infrastructure dependencies.
Sources: CLAUDE.md:100-108, README.md:27-32
Agentic Loop & Tool Execution
The agent operates through a durable execution loop. Tools are scoped per request, and their execution is managed by a Service interface that acts as an ACL boundary.
Tool Architecture
Tools access external systems exclusively through the Service layer. This ensures that whether tools run in-process or in future sandboxed environments (like WASM), they remain constrained by the orchestrator's security policies.
- Native Tools: Statically defined in the
ToolRegistry. - MCP Tools: Merged dynamically at request time via the
McpRegistry. - Service Interface: Provides scoped access to memory banks and external APIs.
Sources: CLAUDE.md:159-165, design/integrations/mcp.md:67-80
Message Handling Flow
When a message arrives, the system follows a specific sequence to resolve context and generate a response.
Persistent Memory System (Hindsight)
Memory is managed by Hindsight, a self-hosted vector memory server. It is structured into "4 networks" (facts, observations, steering rules, and transient context). The system uses a "MemoryProvider" abstraction to ensure domain logic is not tied to the specific HTTP client implementation.
Memory Access Control
Trust tiers are enforced at the memory layer using tag-based filtering. First-party profiles have full access to memory compartments, while third-party or sandboxed integrations are restricted to memories tagged with trust:any.
Sources: CLAUDE.md:100-104, design/integrations.md:46-56
Self-Evolution Ladder
The architecture includes a 6-stage "ladder" for self-evolution, allowing the system to learn from interactions and eventually modify its own capabilities.
Evolution Stages
- Instruction Evolution: Post-conversation extraction of steering rules (Observer pattern).
- Skill Library: Agent-authored reusable code tools (Voyager pattern).
- Typed Calls + Retry: Feedback injection on schema failures (DSPy-inspired).
- Prompt Optimization: Automated search over prompt variants (MIPROv2/ACE).
- Signal Pipeline: Evaluate-rewrite-test-deploy loop.
- Evolutionary Search: Bounded code mutation.
Sources: design/evolution.md:3-80
Evolution Event Persistence
Every fire of the "Observer" (autonomous or manual) is recorded in the evolution_events table to provide an audit trail for the system's learning process.
| Field | Description |
|---|---|
triggered_by | Enum: idle (automatic) or manual (user command). |
payload | JSONB containing ObserverResult (extracted corrections, memories, etc.). |
conversation_id | UUID back-reference to the source transcript. |
Sources: design/evolution.md:103-135
Model Context Protocol (MCP) Integration
MCP allows the integration of third-party servers (e.g., GitHub, Gmail) declaratively. The system treats all MCP servers as untrusted by default, employing schema pinning to prevent "rug-pull" attacks where a tool's schema changes maliciously after approval.
MCP Data Model
Sources: design/integrations/mcp.md:95-125
Trust & Sandboxing
The system defines trust at the code level rather than the database. Servers not in the SHIPPED_TRUSTED_SERVERS allowlist are executed within a sysbox-runc container sandbox with restricted egress and read-only filesystems.
Sources: design/integrations/mcp.md:186-210
Infrastructure & Deployment
Cogmo is deployed as a single container. It requires external services for state and long-running operations:
- PostgreSQL 18: Primary data store with
pgvectorfor memory. - Redis 7+: Inngest queue management and state.
- Inngest: Event-driven durable execution.
- Secrets: Encrypted using AES-256-GCM with keys derived via HKDF from a master key, stored in the
secretstable.
Sources: README.md:27-39, CLAUDE.md:173-177
Cogmo's architecture ensures that high-level agentic behaviors are decoupled from low-level transport and infrastructure, providing a resilient and extensible platform for a personal AI assistant.