bitterbot-desktop: Instructions file for Codex

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:

• 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.
• Failure experiments and procedural lab (failure-experiments.ts, procedural-learning*.ts, learning-strategy*.ts): the default-on shadow service includes a durable coordinator for the existing production skill-evolution pipeline. Idle dream ticks on the default agent run bounded failure experiments on the evolution cadence, independently of the creative-cycle gate; only the task validation gate can promote to canary. Dispatch limits, pause checks, bounded interrupted-proposal retries, canary monitoring and rollback remain in force. The journal is the input queue; the separate procedural SQLite ledger stores references and hashes. automation.enabled: false disables the idle coordinator; mode: "off" disables this service; skills.evolution.enabled: false stops production evolution. The manual service.strategies research lab and verified-experience adapters remain shadow-only, with no research-candidate promotion. See docs/memory/learning-strategy-lab.md and benchmarks/learning-strategy/ for evidence, including failed qualification gates.