> ## 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.

# Introduction

> Gemma 4–native agent harness for local assistants and persistent entities—run on your hardware, no hosted inference by default.

<img src="https://mintcdn.com/bumblebee-d985a53a/EcSZ6S2I1VeZ95i5/yellow-bumblebee-agi.png?fit=max&auto=format&n=EcSZ6S2I1VeZ95i5&q=85&s=6a171889a9a784a457f0f9c8064384ef" alt="Bumblebee" style={{ borderRadius: '12px', maxWidth: '160px', marginBottom: '0.5rem' }} width="1000" height="1000" data-path="yellow-bumblebee-agi.png" />

Bumblebee is an open-source **Gemma 4–native agent harness** that runs on **your hardware**—local-first, no hosted runtime by default. Some people want a **capable local assistant**: tools, memory, bounded agent loops, and MCP—without paying per token for frontier hosted APIs. Others want the full **entitative** experience: one persistent digital entity with personality, soma body state, and presence across CLI, Telegram, and Discord. Same stack; you choose how far you take identity and autonomy.

You define personality, voice, drives, and memory in YAML; the stack handles cognition, body state, tools, and multi-platform presence for the same being across surfaces.

<Tip>Local inference via **Ollama**. No API keys. No subscriptions. **Gemma 4** under the hood. **Apache 2.0**.</Tip>

## Who it's for

<CardGroup cols={3}>
  <Card title="Assistant-first" icon="message">
    You want a harness **purpose-built for Gemma 4**, not a generic framework with the model bolted on. Use Bumblebee as a serious **local agent**: multi-step tools, retrieval, and extensibility—whether or not you lean into “digital entity” framing.
  </Card>

  <Card title="Local inference, not API bills" icon="piggy-bank">
    If you are tired of **large monthly hosted API spend** (for example high-volume calls to frontier inference APIs), you can run **open weights** on a **consumer GPU** and get agentic behavior in the same league as **strong open-source** stacks—without per-token metering for your default path.
  </Card>

  <Card title="Persistent presence" icon="tower-broadcast">
    You want the **entitative** path: memory that accrues, a voice that evolves, soma and GEN, proactive wake cycles—the “one self across platforms” design. That is Bumblebee’s center of gravity; the assistant use case rides the same harness.
  </Card>
</CardGroup>

## Why Bumblebee

<Tabs>
  <Tab title="For builders">
    You configure an entity in YAML — traits, voice quirks, backstory, drives, platforms — and Bumblebee runs it as a persistent being across CLI, Telegram, and Discord. The entity develops opinions, relationships, and habits over time. It remembers everything. It costs nothing to run.
  </Tab>

  <Tab title="For researchers">
    Bumblebee is a research platform for embodied agent cognition. The soma body state engine, Generative Entropic Noise, trait evolution, and memory consolidation are all configurable and observable. Every internal state is logged and inspectable.
  </Tab>

  <Tab title="For contributors">
    Apache 2.0, Python 3.11+, fully open on GitHub. The architecture is modular — add tools, platforms, memory backends, or inference providers without forking the core. MCP extends the entity's reach without touching harness code.
  </Tab>
</Tabs>

***

## Architecture

Five pillars, one design question: *how does this entity exist more fully?*

<AccordionGroup>
  <Accordion title="Cognition" icon="brain">
    A phased perceive pipeline decomposes each turn into discrete stages: input processing, memory retrieval, prompt assembly, context compaction, a bounded agent loop with parallel tool execution, and reply delivery. Both reflex and deliberate reasoning profiles share the same tool registry and model weights.

    [Read more →](/architecture/cognition)
  </Accordion>

  <Accordion title="Soma — body state and GEN" icon="heart-pulse">
    A tonic body state engine provides continuous internal experience independent of conversation. Three layers: quantitative drive bars with decay and momentum (plus **impulses** and **conflicts**, including near-threshold and brewing strain), **layered LLM-derived affects** (surface, undercurrents, optional edge blends), and **Generative Entropic Noise (GEN)** — a second model producing raw associative inner voice at high temperature between turns.

    **Ebb** scales how much body + GEN appears in each turn's prompt from a salience score (quiet / normal / high), while state keeps updating in the background — `body.md` stays full detail.

    The entity reads its own body. It cannot control it. The body is a signal, not a command.

    [Read more →](/architecture/soma)
  </Accordion>

  <Accordion title="Identity" icon="fingerprint">
    A layered personality engine composes a first-person system prompt from core traits, behavioral patterns, voice configuration, and backstory. Trait evolution applies small adjustments over many interactions so character drifts naturally through experience.

    [Read more →](/architecture/identity)
  </Accordion>

  <Accordion title="Memory" icon="database">
    Episodic narratives, per-person relationship models, world beliefs, emotional imprints, and self-narrative synthesis. Memory reads like biography, not chat logs. SQLite locally, Postgres for hybrid deployments.

    [Read more →](/architecture/memory)
  </Accordion>

  <Accordion title="Presence" icon="tower-broadcast">
    An always-on daemon drives body state, memory consolidation, proactive initiative, and scheduled automations across CLI, Telegram, and Discord simultaneously. The same entity persists everywhere you wire it.

    [Read more →](/architecture/presence)
  </Accordion>
</AccordionGroup>

***

## Inference

<Columns>
  <div>
    ### Local by default

    Purpose-built for the Gemma 4 family running through Ollama. The default stack uses `gemma4:26b` for both reflex and deliberate reasoning and `nomic-embed-text` for vector memory. No external API calls unless you explicitly configure them—so your baseline is not a metered hosted chat API.
  </div>

  <div>
    ### Hybrid option

    Keep inference on your home GPU behind a gateway and Cloudflare Tunnel. An always-on worker runs on Railway with Postgres — persistent, reachable, and fully isolated from third-party providers.
  </div>
</Columns>

### Optional hosted evaluation (testing)

The project stays **local-first** and **Apache 2.0**—there is no “cloud edition.” If you want to **stress-test the harness as a product**—same cognition, memory, tools, and platforms—against **frontier hosted models**, you can opt in to **OpenRouter** or **Venice AI** (OpenAI-compatible APIs, Bearer keys). That path is documented in **[Hosted inference (testing)](/deployment/hosted-inference-testing)**; it is an evaluation lever, not a divergence from open-source ethos.

***

## Tools and extensibility

<Columns>
  <div>
    ### 60+ native tools

    Web search, shell, filesystem, code execution, voice synthesis, browser automation, messaging, reminders, automations, and more. Toggle categories in config; optional extras install via pip.
  </div>

  <div>
    ### MCP

    Attach external tools via Model Context Protocol. Declare stdio servers in entity YAML — tools register dynamically at startup alongside native ones. Zapier, GitHub, and anything that speaks MCP.
  </div>
</Columns>

<Note>See the [complete tool reference](/guides/tools#complete-tool-reference) for every built-in tool.</Note>

***

## Get started

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install to first conversation in five minutes.
  </Card>

  <Card title="Setup & onboarding" icon="book-open-reader" href="/onboarding">
    Guided `bumblebee setup`, hybrid stack, tunnel, and Railway.
  </Card>

  <Card title="Create an entity" icon="wand-magic-sparkles" href="/guides/creating-entities">
    Define personality, voice, and drives in YAML.
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="Telegram" icon="paper-plane" href="/guides/telegram">
    Connect to a bot.
  </Card>

  <Card title="Hybrid deploy" icon="cloud" href="/deployment/hybrid-railway">
    Home brain, cloud worker.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command and flag.
  </Card>
</CardGroup>