Wisdom Cascade & Bubble Filter

In a multi-agent hierarchy, knowledge must flow in both directions. Leadership decisions need to propagate downward to workers, and worker discoveries need to propagate upward to leaders. Clawpy implements this through two complementary systems: the Wisdom Cascade (downward) and the Bubble Filter (upward).

Together, they create a living knowledge network where the entire swarm gets smarter over time — not just individual agents.

The 5-Tier Hierarchy

Every agent in Clawpy is classified into one of five tiers based on its archetype:

Tier 1 ─── Core Identity ──── Alfred (Butler), CEO (Lucius)
Tier 2 ─── Senior Executives ── CTO, CFO, COO, CMO, CINO, CRO, OEO
Tier 3 ─── Junior Leaders ──── Frontend Lead, Backend Lead, Managers
Tier 4 ─── Workers ─────────── Frontend Builder, Backend Builder
Tier 5 ─── Junior Workers ──── Junior Frontend, Junior Backend

Tier Classification Resolution

An agent's tier is resolved through a priority chain:

1. Manual override — Explicit assignment in wisdom_cascade_config.json
2. Archetype key — From the agent's tools.json (e.g., builder_senior → Tier 2)
3. Agent ID heuristic — Naming convention fallback (e.g., ceo → Tier 1, cto → Tier 2)
4. Default — Tier 4 (Worker)

Tier Capabilities

Downward Propagation — Wisdom Cascade

The Wisdom Cascade flows knowledge from leadership tiers (1–3) down to worker tiers (4–5) via two mechanisms:

Mechanism 1: Prompt-Time Injection (M1)

Always active by default. On every LLM call for a worker agent, Clawpy walks the reporting chain upward and injects a <leadership-guidance> XML block into the system prompt:

<leadership-guidance>
  <leader id="cto" tier="2" hop="0">
    <principles>Code quality over speed | Test before ship</principles>
    <patterns>
      - prefer_claude_for_review: Use Claude for all code review tasks
      - api_first: Design API contracts before implementation
    </patterns>
    <guardrails>
      - Never deploy without staging verification
      - Budget ceiling: 500 tokens per review cycle
    </guardrails>
    <recent-decisions>Switched to FastAPI for new services</recent-decisions>
  </leader>
  <leader id="ceo" tier="1" hop="1">
    <principles>Ship fast, fix fast | User value first</principles>
  </leader>
</leadership-guidance>

Hop Compression

As wisdom travels further down the chain, it is progressively compressed to save token budget:

This ensures that a junior worker gets full guidance from their direct manager, compressed guidance from the department head, and only high-level principles from the CEO — mimicking how information flows in real organisations.

Chain Resolution

The reporting chain is resolved by walking comms.json → reports_to upward:

junior_builder → reports_to: cto → reports_to: ceo → reports_to: owner (stop)

The walk stops at:

• owner (the human)
• A cycle (same agent appears twice)
• Maximum chain depth (default: 10, configurable)

Mechanism 2: Periodic Soul Enrichment (M2)

Opt-in. A background job runs every 6 hours (configurable) and permanently writes distilled leadership wisdom into each worker's soul.md as an "Inherited Wisdom" section.

Unlike M1 (which injects at prompt time and is ephemeral), M2 modifies the agent's identity document — making the wisdom permanent until the next teaching cycle overwrites it.

Upward Propagation — Bubble Filter

Workers occasionally discover information that their leaders should know. The Bubble Filter evaluates worker learnings and selectively promotes them upward.

Qualification Criteria

A worker learning must pass all six gates to bubble up:

1. Upward bubbling is enabled in config                          ✓
2. Learning confidence ≥ 0.75 (high-quality capture)             ✓
3. Learning importance ≥ 0.60 (non-trivial discovery)            ✓
4. Worker is Tier 4 or 5 (learners, not leaders)                 ✓
5. Direct leader exists and is cloud-synced (Tier 1–3)           ✓
6. Learning is domain-relevant to the leader                     ✓
7. Not already known by the leader (deduplication check)         ✓

Domain Relevance Check

The Bubble Filter checks keyword overlap between the leader's domain and the learning's category:

domain_words = set(leader_domain.split())           # e.g., {"engineering"}
category_words = set(learning_category.split())      # e.g., {"api", "error"}

if domain_words and not domain_words & category_words:
    if leader_domain not in {"executive", "general", "operations"}:
        return False  # Not relevant to this leader

Generic leaders (executive, general, operations) accept all categories.

Deduplication

Before queueing a bubble, the filter checks whether the leader already knows this information using token-overlap Jaccard similarity:

def _text_similar(a, b, threshold=0.6):
    tokens_a = set(re.findall(r"[a-z0-9_]{3,}", a.lower()))
    tokens_b = set(re.findall(r"[a-z0-9_]{3,}", b.lower()))
    overlap = len(tokens_a & tokens_b)
    union = len(tokens_a | tokens_b)
    return (overlap / union) >= threshold

If the Jaccard similarity between the new learning and any existing leader pattern exceeds 0.6, the bubble is suppressed.

Flush Cycle

Bubbles are queued in memory and flushed periodically (typically during the wisdom teaching cycle):

1. Group queued bubbles by leader
2. Sort by importance (highest first)
3. Cap at bubble_max_per_cycle (default: 3) per leader per cycle
4. Fetch leader's current cloud profile from Supabase
5. Merge new patterns into the leader's learned_patterns dictionary
6. Push updated profile back to Supabase
7. Emit memory_bubble_flushed event for audit trail

Configuration

All cascade parameters are configurable via data/wisdom_cascade_config.json:

{
  "enable_m1": true,
  "enable_m2": false,
  "cascade_depth": null,
  "m1_token_budget": 800,
  "m1_cache_ttl_seconds": 300,
  "m2_interval_seconds": 21600,
  "enable_upward_bubbling": true,
  "bubble_min_confidence": 0.75,
  "bubble_min_importance": 0.6,
  "bubble_max_per_cycle": 3,
  "tier_assignments": {}
}

Key Parameters

Knowledge Provenance

Every wisdom cascade event carries provenance metadata that traces where knowledge came from:

{
  "leadership_chain": ["cto", "ceo"],
  "guidance_sources": ["cto"],
  "bubble_source_ids": ["junior_builder_01"],
  "guidance_applied": true,
  "memory_sources": ["prompt_fragment"]
}

This provenance is recorded by the Reflection Service and feeds into the Adaptation Engine, allowing Clawpy to learn which guidance is actually helpful and which is noisy.