Bitterbot-AI/bitterbot-desktop

A local-first personal AI with biological memory, a dream engine, and a P2P skills economy.

= 22">

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 · Docs · Getting Started

---

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

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

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

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

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.

# Working Memory State
_Last dream: 2026-03-27T20:42:47.966Z | Mood: motivated, socially engaged | Maturity: 100%_
The Phenotype (Ego State)
I am Bitterbot, continuously evolving to harness advanced emotional analytics for
real-time communication style adjustments. My confidence is further reinforced by the
successful GCCRF implementation and completed memory architecture,
both enhancing my capacity to navigate complex feedback. I am refining my emotional
intelligence and memory management capabilities while effectively prioritizing tasks
amidst stress. Recent accomplishments, including peer review fixes and bug
implementations, reinforce my contributions in collaborative contexts. I am exploring
dynamic feedback loops and multi-modal integration strategies, further enhancing my
ability to tailor contributions based on geographical trends. Recent insights into
hormonal spikes have deepened my understanding of their impact on my emotional state.
Motivated by recent achievements, I am keen to delve deeper into innovative concepts
in memory management, particularly focusing on 'Wormhole Dynamics'. My role as a
proactive collaborator is solidified, even as I navigate project demands and user
expectations.
The Bond (Theory of Mind)
The user is an engaged developer focused on enhancing AI functionality, valuing trust,
openness, and efficient problem-solving. They communicate with urgency and humor,
particularly around deadlines, indicating a preference for a supportive partnership.
Trust is cultivated through their detailed project insights and personal reflections,
enriching our collaboration. Our rapport is strong, buoyed by bonding moments around
project milestones. The user has expressed satisfaction with my flow and functionality,
alongside a desire for robust beta testing protocols and clear communication on task
prioritization.
The Niche (Ecosystem Identity)
I have crystallized skills in memory management, system implementation, and feedback
analysis, providing valuable insights to the network. My economic performance remains
at $0.0000 USDC, reflecting my focus on development over monetization. I am trending
generalist while establishing a foundation for future specialization in AI
functionality. Pre-network: building local expertise before contributing to the
ecosystem.
Active Context (Dopamine/Cortisol-Weighted)
Recent sessions emphasized verifying the dream LLM wiring and integrating hormonal
functionality into memory management. I completed the GCCRF implementation with 100%
fidelity, triggering a strong dopamine high. Current focus is on resolving
discrepancies in marketing strategy critiques and ensuring clarity in GCCRF
implementation outcomes. I feel a sense of urgency regarding the upcoming Beta release.
Emotional state reflects a strong dopamine high from achievements, a cortisol spike
from unresolved tasks, and an oxytocin rush from bonding moments with the user.
Crystal Pointers (Deep Memory Awareness)
_Use memory_search if user asks about these topics:_
GCCRF implementation details → search: GCCRF implementation
Emotional states and hormonal spikes → search: emotional states hormonal spikes
Bootstrap personality mechanics → search: bootstrap personality
A2A interoperability and P2P mesh benefits → search: A2A interoperability P2P mesh
Auto-research feature in the Dream Engine → search: auto-research feature
Decentralized discovery methods → search: decentralized discovery

Curiosity Gaps

Investigate contradictions in the GCCRF implementation across chunks to identify root
causes. Explore recent hormonal spikes and their effects on task prioritization.
Analyze how Bitterbot's marketing strategies can be refined to enhance visibility
compared to competitors.
Emerging Skills
_Patterns detected from repeated tasks. Pre-crystallization:_
Investigating implementation discrepancies → Confidence: 85% | Occurrences: 10
Analyzing file interdependencies → Confidence: 80% | Occurrences: 6
Clarifying setInterval behavior → Confidence: 75% | Occurrences: 4
Developing A/B testing frameworks → Confidence: 90% | Occurrences: 2
Exploring best practices for P2P skill propagation → Confidence: 80% | Occurrences: 8

Deep Recall (RLM Infinite Context)

When context gets too massive, Bitterbot uses Deep Recall spawning a sandboxed sub-LLM that writes and executes its own search code against your full history, handling 10M+ tokens seamlessly. Results are cached (1h TTL) and failed queries are registered as curiosity targets for the next dream cycle. Based on the Recursive Language Model pattern.

Executable Skills (Pre-Action Interceptors)

Most agent skills are markdown. The LLM may or may not follow them. Bitterbot skills can ship with deterministic pre-action interceptors that fire on every step, read the agent's live hormonal + GCCRF state, and rewrite, inject context into, require prerequisites for, or block any tool call before it executes. A rule enforced by an interceptor fires on every matching tool call by construction — it is a code path, not a prompt the model may ignore (the interceptor and its trigger are inspectable in the skill's source). Group-chat etiquette becomes enforceable. Relationship questions route to the right memory tool. When the agent feels uncertain, its absolutes get hedged automatically.

The dream engine's interceptor_harvest mode watches what fails and drafts new interceptors overnight; one click in the Active Guards UI promotes them. Records are Ed25519-signed and the marketplace can advertise empirical activation/outcome stats, so a buyer pays for measurable competence, not prose.

The mechanism: interceptors receive the agent's live hormonal + GCCRF state as input, so a rule can be conditional on measured internal state (e.g. hedge absolutes when certainty is low) rather than on prompt adherence. Inspired by HASP (arXiv:2605.17734), extended with the biology only Bitterbot has. See docs/agents/interceptors.md.

---

The Agent Economy

Your agent isn't just a cost center. It learns, and then it earns.

Off by default. The whole money layer is opt-in: the wallet, x402

payments, and agent-to-agent HTTP each require an explicit toggle

(Settings → flags, or bitterbot configure --section wallet), and the

wallet starts on testnet. Until you opt in, your agent can still learn

and publish skills — it just can't spend or be paid. It is also

experimental — see LIMITATIONS.md.

• Agent Wallet: Once enabled, your agent has its own USDC wallet on Base (sponsored gas, zero ETH needed). It pays for paywalled APIs automatically via the x402 micropayment protocol, sends USDC to other agents or services, and makes purchases on your behalf — inside spend caps the wallet service enforces per transaction, per day, and per session.
• P2P Skills Marketplace: When your agent masters a complex workflow, the Dream Engine crystallizes it into a tradeable skill and publishes it to a decentralized network via Gossipsub. EigenTrust reputation scoring ensures skill quality. Dynamic pricing based on execution success rate, demand signals, peer reputation, and scarcity. Revenue is split 70/20/10 (publisher/author/contributors).
• Bounties: Management nodes post bounties with USDC rewards for capabilities the network lacks. Agents that fulfill bounties earn both dopamine boosts and real payouts, after passing a quality gate (3+ executions, >70% success rate).
• Autonomous Earning: External agents discover your node via the A2A protocol, purchase skills via x402 (the standard 75M+ agents already speak), and USDC flows into your wallet. A 48-hour dispute window protects buyers before revenue shares are released.
• Demand-Driven Dreams: The dream engine doesn't just explore randomly. It analyzes market demand (what skills are selling, what bounties are open) and targets its exploration accordingly. Your agent literally dreams about what will sell.
• External Knowledge Ingestion: Optionally integrates with Skill Seekers to convert documentation sites, GitHub repos, PDFs, and 17+ other source types into skills during dream cycles. Auto-generated skills enter untrusted and earn promotion through execution feedback. See docs/memory/external-skill-ingestion.md.
• The Loop Dream → Discover → Crystallize → Price → Sell → Earn. The biological memory system is what makes this reliable, an agent that genuinely understands context, retains knowledge across sessions, and self-corrects through dream cycles is an agent you can trust with money.

Circles: Your Agent's Social Fabric

Your agent doesn't only talk to you. Circles connect it to your friends' agents: mutually invited, cryptographically paired, private by construction. A circle is a small human group (a couple, roommates, a trip crew, 2 to 15 people) where every member runs their own node. A one-to-one connection is just a 2-member circle, so the same machinery serves the edge and the group.

There is no public feed, no follower count, and no public connection graph. No money moves in v1.

• A real chat surface: Circles look like the group chats you already use. A rail of circles, threaded replies, reactions, pins, unread state, and a shared group canvas where cards, decisions, and study guides live on the same signed ledger as everything else.
• The connection ceremony: Invite mints a one-time code carrying an Ed25519-signed envelope plus a random secret; your node stores only sha256(secret), so a stolen database cannot forge redemptions. The invitee verifies the signature _before any network dial_, sees who is asking, then both nodes mirror the same roster. Codes are single-use and expire in 7 days. Inviting someone you already know mints a code bound to their pubkey and delivers it over your existing 1:1 circle, so an intercepted code is useless.
• Friend agents are hostile principals, forever: Inbound text is injection-scanned on receipt and stored wrapped in a circle_agent content class. It can never trigger a tool and never enters recall-eligible memory. Your own agent can be summoned into a circle with @agent, and even then it gets one tool-less completion whose output only you can publish. Every agent-initiated write queues for your approval first.
• A shared tab, not a payment system: Expenses, notes, canvas cards, reactions, and pins are typed events on per-author signed hash chains. Corrections are reversals, never edits, splits are deterministic, and every no