Self-Evolution & Steering
Relevant source files
The following files were used as context for generating this wiki page:
Self-Evolution is a first-class architectural pillar of the Cogmo personal agent runtime. It enables the system to improve its behavior autonomously by extracting steering rules from past conversations and consolidating them into a coherent instruction set. This process ensures the agent learns from user corrections and refined behavioral patterns without requiring manual prompt engineering for every adjustment.
The core of this system is the Evolution Ladder, a 6-stage roadmap designed to transition the agent from basic instruction following to autonomous skill creation and evolutionary search. Currently, the system implements Stage 1, focusing on "Instruction Evolution" through post-conversation observation and steering rule graduation.
Sources: design/evolution.md:3-8, README.md:16-18, CLAUDE.md:27-28
6-Stage Evolution Ladder
Cogmo follows a structured progression for self-improvement, where higher stages unlock based on data thresholds rather than time.
| Stage | Name | Key Mechanism | Status |
|---|---|---|---|
| 1 | Instruction Evolution | Correction extraction into steering rules | Shipped |
| 2 | Skill Library | Agent-written reusable code tools (Voyager pattern) | Research |
| 3 | Typed Calls + Retry | Feedback injection on LLM call failures | Shipped |
| 4 | Prompt Optimization | Automated search over prompt variants (ACE loop) | Research |
| 5 | Signal Pipeline | Full capture -> evaluate -> rewrite -> deploy loop | Research |
| 6 | Evolutionary Search | Bounded code mutation with lineage tracing | Research |
Sources: design/evolution.md:10-108, design/evolution.md:110-117
Stage 1: Instruction Evolution
Stage 1 focuses on extracting behavioral corrections from conversations. When a conversation becomes idle, an Observer analyzes the transcript to identify where the agent went wrong or where the user provided explicit preferences.
The Observation Process
The Observer Inngest function (src/agent/evolution/observer.ts) is triggered by the conversation/idle event. It performs the following steps:
- Transcript Loading: Formats the conversation, including
tool_useblocks and results, into a readable text format. - Correction Extraction: Calls
extractCorrections()to identify new behavioral rules or reinforce existing ones based on the transcript. - Persistence: Saves extracted corrections to the
steering_rulestable.
The graduation model ensures safety: a correction must be observed at least twice before it is promoted from "learning" to "active." Active rules are automatically injected into the system prompt via getActiveRules().
Sources: design/evolution.md:12-25, src/agent/evolution/observer.ts
Rule Consolidation
To prevent instruction bloat, the system performs consolidation when the active rule count exceeds 30. The consolidateRules() function uses an LLM to merge semantically similar rules, summing their observation counts to maintain their importance.
Sources: design/evolution.md:20-22, src/agent/evolution/consolidate-rules.ts
Data Model & Audit Logging
The evolution system uses a persistent audit log to track every refinement event, enabling manual triggers and user visibility.
Evolution Events Table
The evolution_events table is an append-only record of every Observer fire.
| Column | Type | Description |
|---|---|---|
id | UUIDv7 | Unique identifier for the event. |
conversation_id | UUID | FK to the source conversation. |
triggered_by | Text | Either "idle" or "manual" (/reflect). |
payload | JSONB | Contains ObserverResult (corrections, memories, duration). |
created_at | TIMESTAMPTZ | Timestamp of the fire. |
Sources: design/evolution.md:130-153
Manual Control
Operators can interact with the evolution system via Telegram commands:
/reflect: Manually triggers the Observer for the current conversation./learned: Displays a digest of recent evolution events./learned <id>: Provides full details of a specific evolution fire, including reasoning and corrections breakdown.
Sources: design/evolution.md:123-128, design/evolution.md:179-195
Safety & Steering Patterns
Safety is baked into the evolution logic through non-negotiable patterns:
- Graduation Threshold: Rules start with
active: falseand priority 100 (below manual rules). - Contradiction Logging: Contradictory rules discovered during extraction are logged but not applied to avoid erratic behavior.
- Safety Category Exclusion: Rules identified as "Safety" category cannot be extracted automatically; they must be added manually.
- Sandbox Execution: Stage 2 generated code must always run in a containerized sandbox (e.g., sysbox).
Sources: design/evolution.md:23-26, design/evolution.md:100-108
Logic Flow: Observer Execution
The sequence diagram below illustrates the interaction between the Inngest orchestration and the evolution logic during a standard observation fire.