The Agentic Loop
Relevant source files
The following files were used as context for generating this wiki page:
The Agentic Loop is the core operational cycle of Cogmo, responsible for orchestrating interactions between the Large Language Model (LLM), external tools, and the system's persistent memory. It is designed as a modular, layered hub-and-spoke architecture that prioritizes technical user control and self-evolution without the overhead of heavy agentic frameworks.
The loop utilizes raw Anthropic and OpenAI SDKs to manage conversation turns, tool invocation, and state management. By maintaining a thin orchestration layer, Cogmo achieves a lower error rate compared to more complex peer-mesh architectures.
Sources: CLAUDE.md, README.md, design/decisions.md
Core Architecture and Data Flow
The loop operates through a centralized orchestrator that manages the flow of messages and tool results. Unlike immutable graph-based frameworks, Cogmo's loop is designed to be compatible with self-evolution, allowing the system to update its own steering rules and skills over time.
Interaction Flow
When a message is received, the loop follows these primary steps:
- Prompt Assembly: The system prompt is constructed by merging base instructions with active steering rules and retrieved context.
- LLM Invocation: The orchestrator sends the conversation history and available tool definitions to the provider.
- Tool Execution: If the LLM returns
tool_useblocks, the orchestrator executes the corresponding handlers (either in-process, in a container sandbox, or via MCP). - Observation & Evolution: After the interaction, an "Observer" process extracts behavioral corrections to improve future turns.
The diagram shows the iterative nature of the loop where tool results are fed back into the LLM until a final response is generated.
Sources: CLAUDE.md, design/decisions.md, design/evolution.md
Tool Registry and Execution
Cogmo supports a hybrid tool execution model. Tools are categorized by their runtime environment and access level.
| Tool Type | Execution Environment | Description |
|---|---|---|
| Native | In-process (Node.js) | Core utilities like memory access, web search, and file system operations. |
| MCP | Subprocess / Sandbox | Third-party tools provided via the Model Context Protocol (stdio/HTTP). |
| Skills | Container / WASM | Reusable code tools written by the agent or user, executed in sandboxed environments. |
Concurrent Execution
The loop supports consecutive tool coalescing. If multiple tool calls are returned by the LLM and marked with the parallelSafe flag, the orchestrator executes them using Promise.all. This preserves ordering for unsafe tools (like [read, write, read]) while fanning out safe operations to reduce latency.
Sources: design/decisions.md, design/integrations/mcp.md, src/agent/tools.ts
Self-Evolution Stages
The Agentic Loop is not static; it evolves through a 6-stage ladder based on data thresholds.
Stage 1: Instruction Evolution
Triggered by conversation activity, the system extracts "steering rules" from post-conversation transcripts. When an observation count for a specific correction reaches a threshold (e.g., observationCount >= 2), it is promoted to an active rule and injected into the system prompt.
Stage 3: Typed Calls and Retries
The loop implements typed LLM call contracts. On failure, the system injects feedback (the error and the failed output) back into the model to attempt an in-loop repair.
This sequence illustrates the synchronous flow of a single tool turn within the broader agentic loop.
Sources: design/evolution.md, design/decisions.md
Configuration and Setup
The loop's behavior is governed by configurations stored in the database, which are initialized and managed via a guided setup wizard.
- LLM Providers: Configured to route specific models (e.g., Claude 3.5 Sonnet) to preferred endpoints (Anthropic, OpenAI, or OpenRouter).
- Secrets Management: Credentials (API keys, tokens) are stored as encrypted rows in the
secretstable and resolved at runtime, ensuring they never leak into environment variables or logs. - Channel Mapping: Identities from platforms like Telegram are mapped to internal users and profiles, allowing the loop to maintain persistent, scoped memory.
Sources: src/setup/wizard.ts, design/decisions.md, design/integrations/mcp.md
Conclusion
The Agentic Loop represents Cogmo's fundamental capability to act as a persistent, evolving assistant. By combining a strict, single-writer message history with a modular tool registry and a multi-stage evolution pipeline, the loop provides a durable execution environment that learns from every user interaction without sacrificing the predictability of a hub-and-spoke architecture.