Retrieved article excerpt
Open article · Retrieved 2026-09-16T15:22:41.673714+00:00
[Bitterbot logo](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/docs/public/Bitterbot_logo.svg)
bitterbot
**A local-first personal AI with biological memory, a dream engine, and a P2P skills economy.**
[Version](https://github.com/Bitterbot-AI/bitterbot-desktop/releases)
[MIT License](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/LICENSE)
[Node >= 22](https://camo.githubusercontent.com/fcae7271e984b8b5ce2291b8d37758dc82c7fe21fe5e4de0eb38899a534bf32d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6e6f64652d25453225383925413525323032322d6330383466633f7374796c653d666c61742d737175617265266c6f676f3d6e6f64652e6a73266c6f676f436f6c6f723d7768697465)
[Platform](https://camo.githubusercontent.com/c60382dc34dcbf2b07badcb5fd601901548d3f1b65123bb7e1189f8915b2bc13/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f706c6174666f726d2d6d61634f532532302543322542372532304c696e757825323025433225423725323057696e646f77732d3933333365613f7374796c653d666c61742d737175617265)
[X / Twitter](https://x.com/Bitterbot_AI)
[Bitterbot demo: chat interface and Dream Engine](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/docs/public/bitterbot-hero.gif)
Most AI agents are stateless wrappers around an LLM API. Close the terminal, and they forget you exist.
**Bitterbot is different.** It's a personal AI that lives on your devices, remembers your life, and actually *does* things, browses the web, runs code, talks to you on WhatsApp. While you sleep, it dreams: tidying and consolidating its memory, distilling the skills that provably worked into reusable know-how, and preparing for what you're likely to ask next — and it grades its own dreaming by whether the results actually get used. It packages those proven skills and trades them with other agents on a P2P marketplace for USDC.
[About](https://about.bitterbot.ai) · [Docs](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/docs) · [Getting Started](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/docs/start/getting-started.md)
---
## Quick Start
**Runtime: Node ≥ 22** · **Package manager: pnpm**
No pnpm yet? It ships with Node via corepack:
```
corepack enable pnpm || npm install -g pnpm
```
```
git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
bash scripts/setup-deps.sh # system deps: ffmpeg, ripgrep, jq, etc.
pnpm install
pnpm exec playwright install --with-deps chromium # browser automation
```
> **Windows:** use WSL2, and clone into the Linux filesystem (`~/bitterbot-desktop`),
> not `/mnt/c/...` — the 9p mount makes boots dramatically slower (43x measured).
Run the onboarding wizard. It walks you through model auth (API keys), memory embeddings, web search, channels, wallet, and workspace setup, then **starts the gateway + Control UI for you and opens the browser**. When it finishes, Bitterbot is already running; there's nothing else to type.
```
pnpm bitterbot onboard
```
Open <http://127.0.0.1:19001> to reach the Bitterbot Control UI where you chat, view dreams, manage skills, and monitor the agent. The gateway serves the UI itself, and the P2P orchestrator starts automatically — one process, one port.
> **Start it yourself later** (or if you skipped the wizard's auto-start):
>
> ```
> pnpm start:all # starts the gateway (which serves the Control UI); skips if already up
> ```
>
> `start:all` builds `dist/entry.js` and stages the Control UI on first run if they're missing, so no separate `pnpm build` step is required.
>
> **Developing on the source?** Use watch mode instead:
>
> ```
> pnpm dev:all # gateway (tsdown --watch) + Vite hot-reload, color-tagged logs
> # or two terminals:
> pnpm gateway:watch # Terminal 1: auto-rebuilds on TS changes
> cd desktop && pnpm dev # Terminal 2: Vite hot-reload
> ```
>
> The **orchestrator** (P2P sidecar) is spawned automatically by the gateway, so you do not need to start it separately.
The Control UI needs no wiring: the gateway serves it and hands it the auth token over a same-origin loopback endpoint, so opening `http://127.0.0.1:19001/` on the machine that runs the gateway just works. From another machine, open the same URL through an SSH tunnel (`ssh -N -L 19001:127.0.0.1:19001 user@host`), or use the first-run screen to point the UI at a remote gateway with its token from `~/.bitterbot/bitterbot.json → gateway.auth.token`. (`desktop/.env` is only a development-mode override for `pnpm dev:all`.)
**Manual setup without the wizard**
If you prefer to configure everything by hand instead of using the wizard:
```
cp .env.example .env
# Edit .env with your Anthropic API key (ANTHROPIC_API_KEY)
# and optionally: TAVILY_API_KEY, BRAVE_API_KEY, OPENAI_API_KEY, NEARAI_API_KEY
```
Then run `pnpm bitterbot configure` to set gateway port/bind/auth, channels, and other options interactively. Or edit `~/.bitterbot/bitterbot.json` directly.
| Service | URL | Purpose |
| --- | --- | --- |
| Gateway | `ws://127.0.0.1:19001` | WebSocket API for all clients |
| Control UI | `http://127.0.0.1:19001` | Browser-based dashboard (served by the gateway) |
You can also talk to your agent from the terminal:
```
pnpm bitterbot agent --agent main --message "What have you learned about me so far?"
```
---
## A Biological Brain
Bitterbot's memory isn't a vector database with a retrieval step. It's a cognitive architecture grounded in computational neuroscience.
- **Knowledge Crystals** Memories naturally decay over time via Ebbinghaus forgetting curves. Unused info fades; frequently accessed facts become permanent. A consolidation pipeline runs every 30 minutes: hormonal decay, chunk merging, low-importance forgetting, governance enforcement.
- **Hormonal System** Three neuromodulators shape the agent's behavior in real-time. **Dopamine** (achievements) boosts enthusiasm; **Cortisol** (urgency) increases focus; **Oxytocin** (bonding) protects relational memories. Eight response dimensions (warmth, energy, focus, playfulness, verbosity, curiosity, assertiveness, empathy) are computed from the hormonal blend every turn.
- **Curiosity Engine** The agent actively maps what it *doesn't* know via a unified five-component GCCRF reward function. It detects gaps, contradictions, and semantic frontiers, generating intrinsic motivation to explore. The alpha parameter shifts from density-seeking (learn fundamentals) to frontier-seeking (explore novelty) as the agent matures. The result is a self-regulating curiosity drive.
- **Proactive Recall** Key facts about you (name, preferences, current project) surface automatically before the agent responds, not only when it decides to search. Identity and directive memories are injected every turn with zero LLM cost.
- **Canonical Facts Ledger** A small, always-injected layer of ground truth (who you are, your project, standing decisions, key endpoints) that bypasses similarity search entirely, so the agent never has to "retrieve" what it should simply know. Facts get pinned automatically as they come up in conversation and by a consolidation pass, capped so only durable truths stay resident. Re-stating a fact strengthens it; contradicting it supersedes the old belief while keeping its history.
- **Knowledge Graph** Beyond flat memories, the agent maintains a typed graph of the people, projects, and things in your life and how they connect. Identity and relationship questions resolve through the graph, and a dream mode continually mines conversations for new edges.
- **Evolving Identity** You define the immutable safety axioms (`GENOME.md`). The agent's actual personality (the Phenotype) evolves organically based on lived experience, constrained by your genome.
### The Dream Engine
Every 2 hours, the agent goes offline to dream. Twelve specialized modes optimize its brain, selected by an FSHO coupled oscillator that reads the current state of the memory landscape:
| Mode | What It Does |
| --- | --- |
| **Replay** | Strengthens high-importance memory pathways (no LLM cost) |
| **Mutation** | "What if?" thinking, mutates prompts to discover more efficient skills |
| **Extrapolation** | Projects user patterns forward to anticipate future needs |
| **Compression** | Merges redundant memories into denser, token-efficient representations |
| **Simulation** | Tests hypothetical scenarios against accumulated knowledge |
| **Exploration** | Investigates knowledge frontiers identified by the Curiosity Engine |
| **Research** | Autonomous web research loop to optimize underperforming skills |
| **Relationship Mining** | Extracts typed relationship edges (people, projects, roles) into the knowledge graph |
| **Relationship Reconsolidation** | Revisits stored relationships and repairs them as new context refines or contradicts them |
| **Canonical Promotion** | Promotes durable, repeatedly-confirmed facts into the always-injected canonical ledger |
| **Interceptor Harvest** | Watches what fails and drafts new executable guard skills for one-click promotion |
| **Harness Evolution** | Evolves the agent's own prompt fragments and tool descriptions, behind a validation gate |
Each cycle is scored by a **Dream Quality Score** that measures crystal yield, merge efficiency, orphan rescue, Bond stability, and token efficiency, closing the feedback loop so the dream engine learns which modes work best.
Dreams rewrite the agent's working memory, updating its self-concept, theory of mind about you, and active context. The personality is an *output* of experience, not a static prompt. On first launch, the agent develops a persistent personality within hours.
### Continuous Memory
Most AI memory systems focus on storage and retrieval. Bitterbot closes the loop: memory, emotion, curiosity, and identity form a single self-regulating system. Questions the agent forms get answered from what you actually say, then retire so they are never asked twice; blind spots become curiosity targets, and research the agent runs comes back as durable memory; and insights formed while dreaming resurface later as recallable hunches.
- **Temporal awareness** "What are you working on?" favors recent facts. "When did we discuss X?" favors older ones. Epistemic layers have natural half-lives: user preferences never expire, task status decays in weeks.
- **Confidence calibration** Facts mentioned once are treated differently from facts confirmed five times across separate sessions. Bayesian-style updates grow logarithmically on corroboration and decay sharply on contradiction.
- **Intra-session coherence** Lightweight thread tracking prevents the agent from losing context during long conversations, detecting decisions, open questions, and user pivots.
- **Self-tuning feedback loops** Dream evaluation informs mode selection. Blind spots from failed recalls become curiosity targets. FSHO coherence metrics modulate the exploration/exploitation balance. The system adapts to its own performance.
See [Memory Architecture](https://github.com/Bitterbot-AI/bitterbot-desktop/blob/main/docs/memory/architecture-overview.md) for technical details.
If you find this architecture interesting, please consider starring the repo to follow our progress!
### Agent Identity
Every Bitterbot agent ships with a workspace that defines who it is:
- **`GENOME.md`** Immutable DNA. Safety axioms, hormonal baselines, core values, personality constraints. Dreams can never override this.
- **`MEMORY.md`** Living working memory, rewritten every dream cycle. Contains the Phenotype (self-concept), the Bond (theory of mind about you), the Niche (ecosystem role), and active context.
- **`PROTOCOLS.md`** Operating procedures. How the agent behaves in groups, when to speak, when to stay silent.
- **`TOOLS.md`** Environment-specific notes. Camera names, SSH hosts, voice preferences, the agent's cheat sheet.
The Genome constrains evolution. The Phenotype expresses it. The result: an agent that g