Scallopbot

<p align="center"> <img src="assets/scallop.png" alt="ScallopBot" width="120" height="120"> </p> <h1 align="center">ScallopBot</h1> <p align="center"> <strong>A bio-inspired cognitive architecture for personal AI agents.</strong><br> <em>Bridging the cognition gap in OpenClaw-compatible agent systems.</em> </p> <p align="center"> <a href="https://github.com/tashfeenahmed/scallopbot/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/tashfeenahmed/scallopbot/ci.yml?branch=main&style=for-the-badge&label=build" alt="CI status"></a> <a href="https://github.com/tashfeenahmed/scallopbot/releases"><img src="https://img.shields.io/github/v/release/tashfeenahmed/scallopbot?style=for-the-badge" alt="GitHub release"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=for-the-badge" alt="Node.js"></a> </p> <p align="center"> <a href="Paper2026.pdf"><strong>Read the Paper</strong></a> </p>

---

Open-source personal AI agents like OpenClaw excel at tool orchestration but lack genuine cognitive depth: no memory lifecycle, no self-reflection, no autonomous reasoning. ScallopBot addresses this cognition gap with a bio-inspired cognitive architecture that maintains full compatibility with the OpenClaw skill ecosystem.

ScallopBot runs on your own server, routes each request to the cheapest model that can handle it, tracks every cent in real time, and fails over across 7 LLM providers automatically. It connects to Telegram, Discord, WhatsApp, Slack, Signal, Matrix, a CLI, and a REST/WebSocket API -- all from a single Node.js process.

The architecture is validated against 30 research works from 2023--2026 across six domains (memory retrieval, lifecycle management, associative reasoning, sleep-inspired consolidation, affect modelling, and proactive intelligence). The full cognitive pipeline operates at an estimated $0.06--0.10 per day.

Benchmark Results

Evaluated on the LoCoMo long-conversation memory benchmark (1,049 QA items, 5 conversations, 138 sessions):

| Metric | OpenClaw | ScallopBot | Improvement | |--------|:--------:|:----------:|:-----------:| | F1 | 0.38 | 0.48 | +26% | | Exact Match | 0.24 | 0.30 | +25% |

F1 by question category:

<p align="center"> <img src="assets/locomo-f1-by-category.png" alt="LoCoMo F1 by question category" width="800"> </p>

| Category | OpenClaw | ScallopBot | Delta | |----------|:--------:|:----------:|:-----:| | Single-hop | 0.14 | 0.20 | +0.06 | | Temporal | 0.26 | 0.34 | +0.08 | | Open-domain | 0.07 | 0.09 | +0.02 | | Multi-hop | 0.32 | 0.42 | +0.10 | | Adversarial | 0.77 | 0.97 | +0.20 |

Adversarial questions show the largest gain (+0.20) driven by cognitive pipeline features and strict answering constraints. Multi-hop benefits from memory fusion and NREM dream consolidation.

Cognitive Architecture

ScallopBot's cognitive layer is organised into six subsystems, orchestrated by a three-tier heartbeat daemon:

| Tier | Interval | Operations | |------|----------|------------| | Pulse | 5 min | Health monitoring, retrieval auditing, affect EMA update | | Breath | 6 h | Decay engine, memory fusion, forgetting | | Sleep | Nightly | Dream cycle (NREM+REM), self-reflection, SOUL re-distillation, gap scanning |

Bio-Inspired Dream Cycle

A two-phase sleep cycle runs during the nightly heartbeat. NREM consolidation clusters and merges fragmented memories across topic boundaries into coherent summaries. REM exploration uses high-noise spreading activation to discover non-obvious connections between memories, with an LLM judge evaluating novelty, plausibility, and usefulness of discovered associations.

Affect-Aware Interaction

Zero-cost emotion detection using AFINN-165 lexicon with VADER-style heuristics, mapped to the Russell circumplex model. A dual-EMA system tracks both session-level mood (2-hour half-life) and baseline mood trends (3-day half-life). An affect guard ensures emotional signals inform agent awareness without contaminating instructions.

Self-Reflection and SOUL Evolution

Nightly composite reflection analyses recent sessions across four dimensions (explanation, principles, procedures, advice). Extracted insights are merged into a living SOUL.md personality document, enabling continuous self-improvement through an evolving system prompt -- no model fine-tuning required.

Proactive Intelligence

A gap scanner identifies unresolved questions, approaching deadlines, and behavioural anomalies. Delivery is gated by a configurable proactiveness dial (conservative/moderate/eager) and a trust feedback loop that calibrates future proactive behaviour based on user engagement signals.

Spreading Activation

ACT-R-inspired spreading activation over typed relation graphs (UPDATES, EXTENDS, DERIVES) with 3-step propagation, fan-out normalisation, and Gaussian noise to prevent deterministic retrieval. The same pure function powers both normal retrieval and REM dream exploration (with elevated noise).

Key Features

Hybrid Memory Engine

SQLite-backed memory with ACID guarantees. Combines BM25 keyword scoring with semantic embeddings (Ollama/OpenAI) and optional LLM re-ranking. A complete memory lifecycle includes exponential decay with category-specific half-lives (14 days for events to 346 days for relationships), BFS-clustered fusion, and utility-based forgetting with soft-archive before hard-prune.

Cost-Aware Model Routing

Every API call is priced at the token level using a built-in pricing database covering 50+ models. A complexity analyzer scores each request and routes it to the cheapest capable tier: fast (Groq, Moonshot), standard (OpenAI, xAI), or capable (Anthropic). Daily and monthly budgets gate requests before they're sent. Provider health is tracked per-call -- consecutive failures trigger automatic failover with exponential backoff and jitter.

Local-First Voice Pipeline

Speech-to-text via faster-whisper (CTranslate2-optimized Whisper) and text-to-speech via Kokoro (82M param ONNX model) run entirely on-device with zero API cost. Cloud providers (Groq STT, OpenAI TTS) serve as automatic fallbacks. Telegram voice messages are transcribed inline; voice replies are synthesized when enabled.

Skills-Only Architecture

All capabilities -- bash, browser, file I/O, git, Docker, PDF, web search, memory -- are implemented as self-contained skills using the OpenClaw SKILL.md format. Skills declare their own requirements (binaries, env vars, OS) and are gated at load time. Community skills install from ClawHub with a single CLI command.

Daily Cost Breakdown

At 100 messages/day with Groq for fast-tier operations:

| Operation | Calls/Day | Daily Cost | |-----------|:---------:|:----------:| | Primary conversation | 100 | $0.03 | | Memory re-ranking | 100 | $0.003 | | Relation classification | 50 | $0.0015 | | Affect classification | 100 | $0 (lexicon) | | Decay/fusion (Breath ticks) | 48 | $0.005 | | Dream cycle (nightly) | 15--20 | $0.005 | | Self-reflection (nightly) | 2 | $0.002 | | Gap scanner (nightly) | 3--5 | $0.001 | | Total | | $0.047--0.10 |

The entire cognitive pipeline -- dreams, reflection, affect, gap scanning -- adds approximately $0.02/day to the base conversation cost.

Quick Start

git clone https://github.com/tashfeenahmed/scallopbot.git
cd scallopbot
npm install

cp .env.example .env
# Add at least one LLM provider API key

npm run build
node dist/cli.js start

Requires Node.js 22+.

Providers

| Provider | Default Model | Best For | |----------|--------------|----------| | Anthropic | Claude Sonnet 4 | Complex reasoning, coding | | Moonshot | Kimi K2.5 (extended thinking) | Cost-effective daily driver | | OpenAI | GPT-4o | General tasks | | xAI | Grok 4 | Real-time information | | Groq | Llama 3.3 70B | Ultra-fast inference | | Ollama | Any local model | Privacy, offline use | | OpenRouter | 100+ models | Maximum flexibility |

Configure one or more in .env. The router handles selection and failover automatically.

Bundled Skills

16 skills ship out of the box:

| Skill | Description | |-------|-------------| | bash | Execute shell commands | | read_file | Read file contents | | write_file | Create/overwrite files | | edit_file | Make targeted edits | | browser | Web automation (agent-browser from Vercel Labs) | | web_search | Search via Brave API | | memory_search | Query the hybrid memory engine | | reminder | One-time, interval, and recurring cron reminders | | pdf | Create PDFs with Typst, read with poppler, edit with qpdf | | git | Version control operations | | npm | Package management | | docker | Container management | | telegram_send | Send messages programmatically | | goals | Track and manage goals | | triggers | Define event-based triggers | | progress | Report progress to the user |

Install community skills from ClawHub:

node dist/cli.js skill install elicitation

Channels

| Channel | Features | |---------|----------| | Telegram | Voice transcription, voice reply, file upload/download, photo analysis, per-user onboarding | | Discord | Slash commands, mention-based chat, DM support | | WhatsApp | Regular account (no Business API needed), QR auth, media support | | Slack | App-based integration | | Signal | End-to-end encrypted messaging | | Matrix | Federated chat | | CLI | Interactive terminal session with session resume (-s <id>) | | REST API | `