Bitterbot is a local-first personal AI agent that runs on a user’s devices, keeps persistent memories, performs tasks, and can exchange reusable skills with other agents. It is intended for people who want a personal assistant that remains available across conversations and activities. The catalogue entries provide instructions and agents for working with Bitterbot.
Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add instructions/bitterbot-ai/bitterbot-desktop/agents-mdgit clone --depth 1 https://github.com/Bitterbot-AI/bitterbot-desktopWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/instructions/bitterbot-ai/bitterbot-desktop/agents-md)<a href="https://agentmods.dev/instructions/bitterbot-ai/bitterbot-desktop/agents-md"><img src="https://agentmods.dev/badge/instructions/bitterbot-ai/bitterbot-desktop/agents-md.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.02569 | $0.02569 |
| Opus 5 | $0.01285 | $0.01285 |
| Sonnet 5 | $0.00514 | $0.00514 |
| Haiku 4.5 | $0.00257 | $0.00257 |
Grade A, and why
bitterbot-desktop AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 150 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Bitterbot — Repository Guidelines
What is Bitterbot?
A self-hosted AI agent gateway with a biological memory system that dreams, gets curious, and evolves a personality. Bitterbot connects to your chat apps (WhatsApp, Telegram, Discord, Signal, Slack, and more) and runs AI agents that actually remember — with a dream engine that consolidates knowledge while idle, a curiosity function that drives self-directed learning, a hormonal system that shapes personality in real-time, and an economic layer that lets agents transact. Agents share skills through a P2P marketplace, earn reputation, and develop persistent identities across sessions.
What Makes Bitterbot Different
1. Memory System (src/memory/)
A consciousness-inspired memory pipeline with no equivalent in any other agent framework:
- Knowledge Crystals: Atomic memory units with embeddings, semantic types (fact, preference, skill, episode, insight, goal, relationship, task_pattern), importance scores, and a full lifecycle (generated → activated → consolidated → archived → expired). Skills are
frozen(immune to decay). - Consolidation Pipeline: Runs every 30 minutes — hormonal decay, Ebbinghaus importance recalculation, chunk merging (cosine ≥ 0.92), low-importance forgetting, governance TTL enforcement, stalled goal detection.
- Session Transcript Indexing: Conversations are automatically chunked, embedded, and made searchable. The agent can recall prior exchanges semantically.
- Governance: Sensitivity tagging (normal/personal/confidential), TTL enforcement, audit trails on all memory operations. Anti-catastrophic forgetting safeguards.
- User Profile: Automatically learned preferences (directive, world_fact, mental_model, experience types) persisted across sessions.
2. Dream Engine (src/memory/dream-engine.ts)
The agent thinks while it sleeps. Every 2 hours, the dream engine runs autonomous cycles with 7 modes:
- Replay: Re-process recent high-importance memories to strengthen retention.
- Mutation: LLM-driven creative variation of existing knowledge — "what if?" thinking.
- Extrapolation: Project existing patterns forward to anticipate future needs.
- Compression: Merge redundant or overlapping memories into denser representations.
- Simulation: Test hypothetical scenarios against accumulated knowledge.
- Exploration: Investigate knowledge frontiers — areas where the agent's understanding is thin.
- Research: Autonomous web research driven by curiosity targets (autoresearch integration from Karpathy's loop).
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 6d ago First seen · 150 lines · 2,569 tokens per session scan A 767b9e62ffc7
bitterbot-desktop AGENTS.md is an instructions file published in the GitHub repository Bitterbot-AI/bitterbot-desktop (2,460 stars, last pushed today), licensed MIT. It adds 2,569 tokens to every session, about $0.0128 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other instructions, from other repositories
mentedb copilot-instructions.md
Copilot instructions for nambok/mentedb, covering mentedb development instructions, project overview, workspace structure, build, test, and lint and key types.
neurodivergent-memory copilot-instructions.md
Copilot instructions for jmeyer1980/neurodivergent-memory, covering neurodivergent-memory — agent bootstrap instructions, what this server is, canonical tag schema, districts and available mcp tools (quick reference).
agidb CLAUDE.md
Instructions for rohansx/agidb, covering agidb — claude code instructions, naming, before changing anything, agent skills and issue tracker.
coworker AGENTS.md
Instructions for Array-Ventures/coworker, covering agents.md, critical: mastra skill required, project overview, commands and installation.
mentedb CLAUDE.md
Claude Code instructions for nambok/mentedb, covering mentedb development instructions, project overview, workspace structure, build, test, and lint and key types.
coworker CLAUDE.md
Instructions for Array-Ventures/coworker: This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.