Skip to content

architecture.md

Latest commit

 

History

History
90 lines (68 loc) · 6.25 KB

architecture.md

File metadata and controls

90 lines (68 loc) · 6.25 KB
Raw

Metacognitive Architecture

This document visualizes the metacognitive architecture of Vibe Check and explains how the components work together to create a complete pattern interrupt system for AI agents.

System Architecture

                          ┌────────────────────────────────────┐
                          │         User + AI Agent            │
                          └───────────────┬────────────────────┘
                                          │
                                          ▼
                ┌─────────────────────────────────────────────────┐
                │                  Agent Workflow                  │
                │                                                 │
                │    ┌───────┐      ┌───────┐      ┌───────┐      │
                │    │Planning│ ──▶ │Implement│ ──▶ │ Review │      │
                │    └───┬───┘      └───┬───┘      └───┬───┘      │
                │        │              │              │          │
                └────────┼──────────────┼──────────────┼──────────┘
                         │              │              │           
                         ▼              ▼              ▼           
┌────────────────────────────────────────────────────────────────────────┐
│                      Metacognitive Layer (Vibe Check)                   │
│                                                                         │
│  ┌─────────────────┐    ┌─────────────────────┐  │
│  │   vibe_check    │◀──▶│     vibe_learn      │  │
│  │                 │    │                     │  │
│  │ Pattern Interrupt│    │ Self-Improving      │  │
│  │    Mechanism    │    │   Feedback Loop     │  │
│  └────────┬────────┘    └─────────┬───────────┘  │
│           │                       │               │
└───────────┼──────────────────────┼───────────────────────┼───────────────┘
            │                      │                       │                
            ▼                      ▼                       ▼                
┌───────────────────┐                 ┌───────────────────────────┐
│  Phase-Specific   │                 │  Pattern Recognition      │
│   Metacognitive   │                 │    Database and          │
│    Questions      │                 │   Category Analysis       │
└───────────────────┘                 └───────────────────────────┘

Component Interactions

1. vibe_check (Pattern Interrupt)

The vibe_check tool serves as the primary pattern interrupt mechanism. It works by:

  1. Receiving the current plan or thinking from the agent
  2. Analyzing it for potential misalignments, tunnel vision, or overengineering
  3. Generating phase-appropriate metacognitive questions
  4. Identifying potential pattern matches with previous issues

The output creates a moment of pause and reflection, forcing the agent to reconsider its approach before continuing. This is critical because LLM agents lack natural mechanisms for self-doubt and course correction.

2. vibe_learn (Feedback Loop)

The vibe_learn tool creates a self-improving feedback loop by:

  1. Recording specific instances of mistakes and their solutions
  2. Categorizing these patterns into meaningful groups
  3. Building a knowledge base of common error patterns
  4. Feeding this information back into the pattern recognition process

Over time, this creates a more sophisticated pattern recognition system that can identify potential issues earlier and with greater accuracy.

Integration Flow

The three components can be used independently but are designed to work together in an integrated metacognitive layer:

  1. Planning Phase: vibe_check identifies potential issues in the initial plan and encourages simplification if overengineering is detected.

  2. Implementation Phase: vibe_check with higher confidence provides more focused feedback on specific implementation decisions, referencing patterns from vibe_learn.

  3. Review Phase: vibe_check ensures the final solution aligns with the original intent, while vibe_learn captures any issues that were identified for future improvement.

  4. Across Workflows: As more patterns are recorded via vibe_learn, the pattern recognition capabilities of the system improve, making vibe_check increasingly effective at identifying potential issues early.

Metacognitive Principles

This architecture embodies several key principles from metacognitive theory:

  1. External Reflection: Providing the reflection capabilities that agents lack internally
  2. Strategic Interruption: Timing interrupts to maximize impact on the workflow
  3. Phase Awareness: Tailoring metacognitive feedback to different cognitive stages
  4. Pattern Recognition: Leveraging past experiences to improve future interventions
  5. Complexity Management: Summarizing large context windows to keep reasoning focused without overwhelming the agent

The result is a complete metacognitive layer that compensates for the inherent limitations of LLM agents in questioning their own reasoning processes.