Bitterbot Desktop: A Local-First Agent With Decaying Memory and a P2P Skills Market

The problem is that your agent forgets you between sessions

The README opens with the diagnosis: most AI agents are stateless wrappers around an LLM API, and when you close the terminal they forget you exist. Bitterbot's answer is to keep the agent on your own machine and give it a memory that changes shape over time. The intended user is one person running one agent on one desktop, not a team sharing a hosted assistant. That framing matters because almost every design decision downstream follows from it. Memory lives in a local store, the gateway binds to loopback by default, and the P2P layer is a sidecar rather than a hosted service. If your use case is a shared support bot or a multi-tenant assistant, the local-first premise is working against you rather than for you.

Knowledge crystals decay on an Ebbinghaus curve, and that is the whole design

Bitterbot does not describe its memory as a vector database with a retrieval step. According to the README, it is a cognitive architecture with three moving parts. First, memories are stored as knowledge crystals that decay over time using Ebbinghaus forgetting curves: unused information fades, frequently accessed facts become permanent. Second, a consolidation pipeline runs every 30 minutes and performs hormonal decay, chunk merging, low-importance forgetting, and governance enforcement. Third, three neuromodulators (dopamine for achievements, cortisol for urgency, oxytocin for bonding) shape eight response dimensions computed every turn: warmth, energy, focus, playfulness, verbosity, curiosity, assertiveness, and empathy. The decay model is the part with real consequences. A system that forgets on a schedule is not a system you can audit by reading a table, because the table is different next week. Whether that is a feature or a liability depends entirely on what you store in it, and the README does not describe an export or freeze mechanism for facts you want pinned.

The dream engine grades itself on whether its output gets used

The README states that while the user sleeps the agent tidies and consolidates memory, distils skills that provably worked into reusable know-how, and prepares for likely next questions. It also says the agent grades its own dreaming by whether the results actually get used. That self-grading loop is the most unusual claim in the repository and also the least specified. There is no described metric, no retention window, and no config key for the grading threshold in the material available. Treat it as a design intent rather than a measurable property until you read the source. The same applies to the curiosity engine, which the README describes as mapping what the agent does not know through a five-component GCCRF reward function that detects gaps, contradictions, and semantic frontiers, with an alpha parameter shifting from density-seeking to frontier-seeking as the agent matures. Both mechanisms are plausible, and both are described at a level of abstraction that makes them hard to verify from the README alone.

Getting it running: pnpm, a wizard, and one port

The runtime requirement is Node 22 or later with pnpm. The README gives corepack as the install path if pnpm is missing. From there the sequence is: clone the repository, run bash scripts/setup-deps.sh for system dependencies (ffmpeg, ripgrep, jq and others), run pnpm install, then pnpm exec playwright install --with-deps chromium for browser automation. Onboarding is a single command, pnpm bitterbot onboard, which walks through model auth, memory embeddings, web search, channels, wallet, and workspace setup, then starts the gateway and Control UI and opens the browser. The gateway serves the UI itself at http://127.0.0.1:19001, and the README notes the P2P orchestrator starts automatically, so it is one process on one port. To restart later, pnpm start:all rebuilds dist/entry.js and stages the UI if missing. For source work, pnpm dev:all runs the gateway under tsdown --watch alongside Vite hot-reload. A terminal path exists too: pnpm bitterbot agent --agent main --message "What have you learned about me so far?". Manual configuration without the wizard means copying .env.example to .env, setting ANTHROPIC_API_KEY and optionally TAVILY_API_KEY, BRAVE_API_KEY, OPENAI_API_KEY or NEARAI_API_KEY, then running pnpm bitterbot configure or editing ~/.bitterbot/bitterbot.json directly. The gateway auth token lives at gateway.auth.token in that file. Remote access is an SSH tunnel to port 19001, or the first-run screen pointed at a remote gateway with that token. One warning in the README is worth repeating: on Windows, use WSL2 and clone into the Linux filesystem, not /mnt/c, because the 9p mount makes boots dramatically slower, with a 43x figure cited.

Windows on WSL2 and the pnpm-only assumption

Two constraints stand out. The first is the WSL2 requirement on Windows, which is not a preference but a performance boundary the README quantifies. The second is that the documented workflow assumes pnpm throughout, with corepack as the fallback. The manual path also assumes you are comfortable editing ~/.bitterbot/bitterbot.json by hand, and the README does not publish a schema for that file beyond the gateway block it names. That is a real gap: configuration drift between the wizard, pnpm bitterbot configure, and direct file edits is exactly the kind of thing that produces bug reports nobody can reproduce. The material also does not describe what happens when the consolidation pipeline runs while the agent is mid-conversation, or how a long-running session interacts with a 30-minute decay cycle. If you plan to keep a session open for hours, that interaction is worth reading the source for before you trust the memory state.

The P2P skills market and where it stops being your call

The README says the agent packages skills that provably worked and trades them with other agents on a P2P marketplace for USDC, with x402 appearing in the repository topics and a2a-protocol alongside it. The orchestrator is a sidecar spawned by the gateway, and it starts automatically, which means the P2P surface is on by default in a standard install. That is a meaningful default for a tool whose selling point is local-first. The README does not describe marketplace pricing, dispute resolution, or what happens when a traded skill turns out to be wrong. It also does not say whether a distilled skill can contain fragments of your own conversations, which is the question anyone running this on personal data should ask first. The MIT licence covers the code, not the contents of your memory store or the skills your agent publishes; those are governed by whatever terms the marketplace applies, and the repository does not state them. This is not legal advice, but the licence file in the repository will not answer the question of what you are agreeing to when a skill leaves your machine.

What it is not: a hosted assistant or a plain RAG stack

The obvious alternative is a hosted assistant with retrieval, or a self-hosted RAG stack over a conventional vector store. The difference in approach is the retrieval step itself. A RAG stack stores embeddings and returns the nearest neighbours on every query; the store is inert between queries and does not change unless you write to it. Bitterbot inverts that: the store mutates on its own schedule through decay, chunk merging, and low-importance forgetting, and the agent's behavioural parameters are computed from the same state every turn. You get a memory that behaves more like a person's and less like a filing cabinet. You lose the ability to answer the question "what does my agent know about X" by running one query, because the answer is time-dependent and the pipeline may have already moved it. For a personal agent on one desktop, that trade is defensible. For anything where you need to reproduce a specific answer months later, it is the wrong tool.

Maintenance cost and what to verify before you commit

The repository is MIT licensed and actively pushed, with v1.0.0 released on 2026-08-28 and orchestrator 0.2.2 and 0.2.1 shortly before it, which suggests the sidecar and the main application version independently. That independent versioning is a maintenance fact worth noting: an orchestrator bump can change P2P behaviour without a corresponding change to the desktop app version you are tracking. The dependency surface is not small. Node 22, pnpm, ffmpeg, ripgrep, jq, and a Playwright Chromium install all need to keep working, and the browser automation dependency in particular tends to require periodic reinstallation as Chromium versions move. The upgrade path itself is plain: pull the repository, rerun pnpm install, and rerun pnpm start:all, which rebuilds dist/entry.js. Before adopting, verify three things against your own setup. Confirm the gateway bind and gateway.auth.token defaults in ~/.bitterbot/bitterbot.json match your network posture. Run one consolidation cycle and inspect what it dropped. And decide in advance whether your agent's distilled skills should be publishable, because the orchestrator starts automatically and the README does not describe an off switch.

Editorial conclusion

Adopt Bitterbot if you want a single-machine personal agent whose memory model you can inspect and whose skills you can package, and if you are comfortable running Node 22 with pnpm and a browser automation dependency on the same box. Do not adopt it if you need a documented multi-user deployment, a stable configuration schema, or a marketplace with published pricing and dispute rules; the README covers the single-operator case and stops there. Before committing, read ~/.bitterbot/bitterbot.json and confirm the gateway.auth.token and gateway bind defaults match your network, run the consolidation pipeline once and inspect what it actually forgets, and check whether the skills your agent distils are ones you are willing to publish to a P2P market at all.

Official sources

1. Bitterbot-AI/bitterbot-desktop on GitHub
2. License: MIT
3. Project website
4. README
5. Releases