Bitterbot-AI/bitterbot-desktop

Bitterbot – a local‑first personal AI

What it is – Bitterbot is an open‑source desktop application that runs a self‑contained AI “agent” on your own computer. Unlike typical chat‑bots that only forward a user’s prompt to a remote LLM, Bitterbot keeps a persistent, biologically‑inspired memory of its interactions, can run tools (web browsing, code execution, WhatsApp messaging), and periodically “dreams” to consolidate what it has learned. It also includes a small peer‑to‑peer (P2P) marketplace where agents can sell verified skills for USDC, though the monetary layer is optional.

Key concepts

• Biological‑style memory – facts are stored as knowledge crystals that decay unless reinforced, mimicking Ebbinghaus forgetting curves. A hormonal system (dopamine, cortisol, oxytocin) modulates the agent’s tone and focus each turn.
• Dream Engine – every few hours the agent goes offline and runs a set of “dream” modes (replay, mutation, compression, research, etc.) that reorganize its memory, create new reusable skills, and score the outcome with a Dream Quality Score.
• Continuous recall – when a query exceeds the token window, Bitterbot spawns a sandboxed sub‑LLM that searches the full 10 M‑token history and caches results.
• Executable skills & interceptors – skills are defined in markdown but can be guarded by deterministic code interceptors that see the agent’s hormonal state and can modify, approve, or block tool calls.
• P2P skill marketplace – agents can publish verified skills (with Ed25519 signatures) and earn USDC on the Base testnet; the wallet is disabled by default.

How to get started

1. Install Node ≥ 22 (the repo ships with Corepack). Enable pnpm:

   corepack enable pnpm || npm install -g pnpm
   

2. Clone the repo and install system dependencies (ffmpeg, ripgrep, jq, etc.) via the provided script:

   git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop
   bash scripts/setup-deps.sh
   pnpm install
   pnpm exec playwright install --with-deps chromium
   

3. Run the onboarding wizard, which walks you through API‑key entry (Anthropic, OpenAI, Tavily, Brave, etc.), memory embedding setup, channel configuration, and optional wallet creation:

   pnpm bitterbot onboard
   

4. After the wizard finishes, the gateway and Control UI start automatically. Open http://127.0.0.1:19001 in a browser to chat, view dreams, manage skills, and monitor the agent.
5. For development you can use the watch mode:

   pnpm dev:all          # hot‑reload gateway + Vite UI
   # or split across two terminals
   pnpm gateway:watch
   cd desktop && pnpm dev
   

Main components

Service	URL	Role
Gateway	ws://127.0.0.1:19001	WebSocket API used by the UI, CLI, and external clients
Control UI	http://127.0.0.1:19001	Browser‑based dashboard that shows chat, dreams, skill library, and diagnostics
Orchestrator (P2P sidecar)	spawned automatically by the gateway	Handles the decentralized skill‑exchange and wallet interactions

Typical use cases

• Personal knowledge assistant – remembers your preferences, project details, and past conversations without re‑prompting an LLM each time.
• Tool‑augmented automation – can browse the web, run shell commands, or send WhatsApp messages on your behalf.
• Research aide – the Dream Engine’s Research mode autonomously fetches information and stores it as a reusable skill.
• Experimentation platform – developers can prototype new memory architectures, hormonal models, or skill interceptors and see them run locally.

Limitations & current status

• The monetary features (USDC wallet, P2P skill trading) are opt‑in and experimental; they run on a testnet and require explicit configuration.
• Memory consolidation and dream cycles are CPU‑intensive; the docs recommend a modern desktop and suggest running the dream engine only when the machine is idle.
• The system relies on external LLM APIs (Anthropic, OpenAI, etc.) for most reasoning; only the deep recall sub‑LLM is sandboxed locally.
• Windows support is limited to WSL2; native Windows execution is not officially tested.
• As of the latest release (2026.2.15) the project is still under active development, and some documentation (e.g., LIMITATIONS.md) warns that certain features may change.

Where to learn more

• Docs – docs/ contains detailed sections on memory architecture, deep recall, interceptors, and the dream engine.
• Live example – the README includes a real MEMORY.md snapshot showing the agent’s self‑generated working memory.
• Community – follow the project on X (@Bitterbot_AI) for updates and discussion.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.