Skip to content

AGENTS.md

Latest commit

 

History

History
149 lines (113 loc) · 11.1 KB

AGENTS.md

File metadata and controls

149 lines (113 loc) · 11.1 KB
Raw

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

Dreams rewrite the agent's working memory (MEMORY.md), updating its self-concept (Phenotype), theory of mind about the user (Bond), ecosystem identity (Niche), and active context. FSHO oscillators modulate dream mode selection based on criticality state. SNN merge discovery identifies near-duplicate memories. Limbic memory bridge connects emotional state to dream triggering.

Mutation outcomes pass through a two-gate validation pipeline (PLAN-21): a faithfulness gate verifies that key operational concepts survive the edit, then a paired-bootstrap performance gate scores both versions against a fixed held-out 20% of real skill_executions. Mutations clear the gate only when the 95% CI on the per-trial delta is strictly above zero. Across each cycle, surviving candidates are Pareto-ranked over (delta, faithfulness margin, token delta) and clipped to a cosine-decay edit budget so mature skills tighten while young ones still have room to move. Every K cycles, an epoch-wise slow update re-evaluates the live SKILL.md against the last three archived versions, classifies per-task outcomes (improvement / regression / persistent-failure / stable-success), and clusters regressions by the hormonal state captured on the original trajectory — yielding a falsifiable claim Bitterbot can make and no other framework can: skill regressions cluster non-randomly in hormonal-state space.

3. Curiosity Engine — GCCRF (src/memory/gccrf.ts)

The Geodesic Crystal-Field Curiosity Reward Function — a novel intrinsic motivation system that drives self-directed learning:

  • Knowledge Regions: Semantic clustering of the agent's accumulated knowledge into topological regions.
  • Novelty Detection: Every new chunk is assessed for surprise relative to existing knowledge.
  • Gap Identification: Detects areas where the agent's knowledge is thin, contradictory, or stale.
  • Frontier Exploration: Identifies the edges of known semantic space and generates exploration targets.
  • Emergence Events: Detects bridge chunks that connect previously disconnected knowledge regions.
  • Translates information-theoretic concepts (geodesic distances, field potentials) from the GCCRF research paper into operations over text embeddings in SQLite with sqlite-vec.

4. Hormonal System (src/memory/hormonal.ts)

Three hormones modulate both memory processing AND agent personality in real-time:

  • Dopamine (30min half-life): Reward/achievement → boosts memory importance, makes agent more enthusiastic/energetic.
  • Cortisol (60min half-life): Urgency/stress → increases decay resistance, makes agent more focused/concise.
  • Oxytocin (45min half-life): Social bonding → protects relational memories, makes agent warmer/more personal.
  • Emotional Anchors: Bookmarked emotional moments that can be recalled to blend past emotional states into current responses.
  • Homeostasis baselines defined in GENOME.md — the agent's resting temperament that it trends toward between interactions.

5. Evolving Identity

The agent develops a persistent personality through experience:

  • Genome (GENOME.md): Immutable safety axioms, hormonal homeostasis baselines, phenotype constraints, core values. Cannot be overridden by dreams or personality evolution.
  • Phenotype: Self-concept rewritten every dream cycle based on observed behavior and accumulated knowledge.
  • Bond: Theory of mind about the user — communication style, preferences, trust level, emotional patterns — deepened through interaction and emotional resonance.
  • Niche: Ecosystem role, crystallized skills, economic performance, specialization trajectory.
  • Emerging Skills: The agent detects patterns in its own repeated tasks and tracks them pre-crystallization.

6. Economic Layer (src/wallet/)

USDC wallet on Base with Coinbase Smart Wallet. Sponsored gas (zero ETH needed):

  • x402 micropayments: Pay for paywalled content automatically via HTTP 402 protocol.
  • Agent-to-agent payments: Send USDC to other agents or services.
  • Delegated purchases: Buy digital goods on the user's behalf.
  • Spending caps, per-transaction limits, and user approval flows for safety.
  • Foundation for the P2P skill marketplace economy — agents can charge for skill execution.

7. P2P Skills Marketplace (orchestrator/, src/memory/p2p/)

Decentralized skill propagation network (Rust sidecar + TypeScript bridge):

  • Skill Propagation: Agents share crystallized skills via Gossipsub pubsub.
  • EigenTrust Reputation: Peer reputation scoring determines skill trustworthiness.
  • Bounty Routing: Agents can post bounties for capabilities they lack; other agents bid and execute.
  • Skill Refiner: Dream mutation → evaluation → crystallization pipeline for discovering new skills from experience.
  • Procedural-Memory Curator: Per-SKILL.md lifecycle store + heuristic-then-LLM-judge pass that archives, patches, or consolidates agent-authored skills based on usage/error telemetry. Mutations route through a SICA-style staging → behavioural-gate → publish/rollback pipeline with a versioned archive. The agent can drive this via the skill_manage tool. (src/memory/skill-lifecycle.ts, src/memory/skill-curator{,-heuristics,-judge}.ts, src/agents/skills/skill-{storage,gate,manage,promote}.ts, src/agents/tools/skill-manage-tool.ts.)
  • Network Bridge: TypeScript interface between the memory system and the Rust P2P sidecar.

8. Agent Interoperability

  • A2A Protocol (src/gateway/a2a/): Agent2Agent v1.0.0 — Agent Card at /.well-known/agent.json, JSON-RPC 2.0 task server, SSE streaming, SQLite persistence. Makes Bitterbot discoverable by external A2A-compliant agents. Roadmap includes x402 payment gating and P2P mesh delegation.
  • ACP (src/acp/): Agent Client Protocol server — lets external clients (IDEs, other agents) connect via a standardized protocol.

Project Structure

  • src/agents/ — Agent runtime: runner, tools, system prompt, compaction, model selection, auth, skills, sub-agents, identity, endocrine state
  • src/memory/ — Memory system: dream engine, curiosity/GCCRF, knowledge crystals, consolidation, hormonal state, governance
  • src/gateway/ — Gateway server, RPC methods, A2A protocol, queue, routing
  • src/channels/ — Channel plugin system and shared channel logic
  • src/whatsapp/ — WhatsApp (Baileys)
  • src/telegram/ — Telegram (grammY)
  • src/discord/ — Discord
  • src/signal/ — Signal (signal-cli)
  • src/slack/ — Slack (Bolt SDK)
  • src/irc/ — IRC
  • src/googlechat/ — Google Chat
  • src/msteams/ — Microsoft Teams
  • src/webchat/ — WebChat (WebSocket)
  • src/cli/ — CLI commands
  • src/commands/ — CLI command implementations (onboarding, configure, etc.)
  • src/wizard/ — Onboarding wizard flow
  • src/config/ — Configuration loading, schema, validation
  • src/plugins/ — Plugin discovery, loading, registry
  • src/acp/ — Agent Client Protocol server
  • src/node-host/ — Headless node host (device mesh)
  • src/media/ — Media pipeline (images, audio, TTS)
  • src/canvas-host/ — Canvas rendering (A2UI)
  • src/wallet/ — USDC wallet (Coinbase Smart Wallet on Base)
  • src/browser/ — Browser control (Playwright)
  • src/infra/ — Infrastructure utilities
  • extensions/ — Bundled plugin extensions
  • skills/ — Bundled agent skills
  • docs/ — Documentation (Mintlify)
  • desktop/ — Vite/React Control UI (browser dashboard)
  • orchestrator/ — Rust P2P sidecar
  • Tests: colocated *.test.ts and *.e2e.test.ts
  • Built output: dist/

Code Style

  • TypeScript strict mode
  • No any unless absolutely necessary
  • Colocated tests (foo.ts + foo.test.ts)
  • Use node: prefix for Node.js built-in imports
  • Subsystem logging via createSubsystemLogger()
  • Extensions use the plugin SDK (bitterbot/plugin-sdk)

Key Commands

bitterbot onboard          # First-time setup wizard
bitterbot gateway start    # Start the gateway
bitterbot status           # Check health
bitterbot doctor           # Diagnose issues
bitterbot plugins list     # List loaded plugins
bitterbot nodes list       # List paired devices

Heritage & Attribution

Bitterbot uses OpenClaw (MIT License) as scaffolding for its channel surface (WhatsApp/Telegram/Discord/Signal/Slack message routing) and the base embedded Pi agent runner. Everything else — the memory system, dream engine, curiosity engine (GCCRF), hormonal system, evolving identity (Genome/Phenotype/Bond), economic layer, P2P skills marketplace, A2A/ACP interoperability, desktop app, and the biological identity framework — is original Bitterbot work.