> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture overview

> The five pillars of Bumblebee's design.

One design question runs through every decision: **how does this entity exist more fully?**

<CardGroup cols={2}>
  <Card title="Cognition" icon="brain" href="/architecture/cognition">
    Phased perceive pipeline, bounded agent loop, parallel tool execution, context compaction.
  </Card>

  <Card title="Soma" icon="heart-pulse" href="/architecture/soma">
    Tonic body state — drive bars; **impulses** (live, cooling, near-threshold) and **conflicts** (active vs brewing); **layered affects** (surface, undercurrents, optional edge); Generative Entropic Noise (sporadic scraps + shape hints); somatic appraisal; **ebb** (salience-tiered body in prompts); read-only `body.md`. **[GEN / noise pipeline →](/architecture/gen-noise-pipeline)** for exact inputs and triggers.
  </Card>

  <Card title="Identity" icon="fingerprint" href="/architecture/identity">
    Personality engine, character voice, drive system, trait evolution.
  </Card>

  <Card title="Memory" icon="database" href="/architecture/memory">
    Episodes, relationships, beliefs, imprints, self-narrative.
  </Card>
</CardGroup>

<Card title="Presence" icon="tower-broadcast" href="/architecture/presence">
  Always-on daemon, proactive initiative, autonomous wake cycles, multi-platform adapters, scheduled automations.
</Card>

<Card title="Autonomous wake" icon="moon" href="/architecture/autonomous-wake">
  Wake triggers, sustained sessions, wide mode, wake voice, optional YAML poker seeds, GEN-grounded disposition, chat status, and worker logging.
</Card>

***

## How a turn flows

Each message passes through the **perceive pipeline** — eleven phases that decompose a turn from raw input to committed memory.

<Steps>
  <Step title="Turn setup">
    Context binding, model validation, early-exit if dormant. Soma fires a `message_received` body event.
  </Step>

  <Step title="Process input">
    Attachment handling (photos as vision, audio transcription), `@path` expansion (up to 4 file refs, 12KB each), speaker prefix for group chats.
  </Step>

  <Step title="Somatic appraisal (input)">
    A fast LLM pass reads the message content and adjusts body-state bars in real time — a confrontational message raises tension, a warm one fills social, a fascinating question spikes curiosity. Applied immediately so the agent's body reflects what was said before it reads `body.md`.
  </Step>

  <Step title="Retrieve memory">
    Semantic episode recall via embeddings, relationship context for the current person, active beliefs, emotional imprints, and the most recent narrative synthesis.
  </Step>

  <Step title="Build prompt">
    Router picks reflex or deliberate. System prompt compiled from personality engine. Volatile context (body state via `body.md`, procedural memory, projects, self-model) injected as a `[Turn context]` preamble.
  </Step>

  <Step title="Ensure context budget">
    Proactive compaction if estimated tokens exceed the threshold. Prunes tool results, summarizes middle turns, protects head and tail.
  </Step>

  <Step title="Run agent loop">
    Bounded tool loop with parallel `asyncio.gather` execution. Post-tool nudges, completion gate (user-visible text includes prior `say()` lines; reflex judges for tool grounding and for “promised but not delivered” work when no work tools ran), up to 6 intermediate deliveries on platforms.
  </Step>

  <Step title="Finalize reply">
    Truncation extension for cut-off responses, fallback generation if empty, sanitization of tool markup.
  </Step>

  <Step title="Deliver reply">
    Inner voice processing (emotional cues, belief hints extracted from thinking text), platform delivery with typing simulation and chunking.
  </Step>

  <Step title="Commit turn">
    Somatic interaction appraisal (how did the full exchange feel?), history append, drive satisfaction, episode creation (if significant), relational upsert, evolution/narrative ticks. All three soma layers persisted.
  </Step>

  <Step title="Noise regeneration">
    GEN produces fresh inner-voice fragments from the conversation that just happened, so the subconscious stays current during active exchanges.
  </Step>
</Steps>

***

## Between turns

The daemon ticks continuously even when nobody is talking:

<Columns>
  <div>
    ### Body state

    * **Bars** decay and accumulate each **daemon heartbeat** (default **120s**; configurable)
    * **Affects** derived from bar state (\~4 min)
    * **GEN noise** generates inner voice (\~90 sec + per-turn)
    * **Idle events** emitted after 60s silence
    * **body.md** flushed after every state mutation
  </div>

  <div>
    ### Agency

    * **Drives** checked against thresholds
    * **Wake cycles** trigger autonomous [perceive](/architecture/autonomous-wake) (wake voice, optional poker + GEN grounding)
    * **Memory consolidation** every \~2 hours
    * **Automations** fire on cron schedules
  </div>
</Columns>

***

## Entitative design

<Tabs>
  <Tab title="Self">
    The entity reads its own body state — it doesn't get told what to feel. The personality engine produces a first-person system prompt that reads like character. Trait evolution drifts slowly through experience.
  </Tab>

  <Tab title="Continuity">
    Episodic memory stores narratives with emotional coloring. Relationships deepen over repeated interaction. Beliefs form and decay. A narrative synthesis pass composes a coherent self-story. The same self persists across platforms and restarts.
  </Tab>

  <Tab title="Agency">
    Drives accumulate during silence. The entity can **wake itself** — wake voice composes a stirring, optional **poker** seeds bias exploration, and **GEN grounding** can merge seeds with inner noise and memory ([Autonomous wake](/architecture/autonomous-wake)). Automations let the entity schedule its own routines.
  </Tab>

  <Tab title="Inner life">
    GEN produces continuous thought between turns. The entity accumulates inner voice fragments during silence. When someone messages after 30 minutes, the body already contains 30 minutes of subconscious activity.
  </Tab>
</Tabs>