A bio-inspired cognitive architecture for personal AI agents.
Bridging the cognition gap in OpenClaw-compatible agent systems.

Read the Paper

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.

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

F1 by question category:

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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

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

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

16 skills ship out of the box:

Install community skills from ClawHub:

node dist/cli.js skill install elicitation

A React + Tailwind + Vite single-page app served from the API channel. Features:

• Real-time chat with markdown rendering and streaming responses
• Debug mode showing tool execution (start/complete/error), thinking steps, and memory operations
• Cost panel with daily/monthly budget bars, per-model breakdown, and a 14-day spending chart
• File send/receive with download links
• Proactive message delivery (reminders, triggers)

Minimal .env:

ANTHROPIC_API_KEY=sk-...           # At least one provider required
TELEGRAM_BOT_TOKEN=...             # Optional: enable Telegram
TELEGRAM_ALLOWED_USERS=123456789   # Optional: restrict access
BRAVE_SEARCH_API_KEY=...           # Optional: enable web search

Budget controls:

COST_DAILY_BUDGET=5.00
COST_MONTHLY_BUDGET=100.00
COST_WARNING_THRESHOLD=0.8

Full reference: .env.example

Natural language scheduling with timezone awareness:

"remind me in 5 minutes to check the build"     -> Interval
"remind me at 10am to take medicine"             -> Absolute time
"remind me every day at 9am to check email"      -> Daily recurring
"remind me every Monday at 3pm about standup"    -> Weekly recurring
"remind me weekdays at 8am to exercise"          -> Weekday recurring

Actionable reminders automatically execute when they contain action words (check, search, get, find).

+-----------------------------------------------------------------+
|                          SCALLOPBOT                              |
+-----------------------------------------------------------------+
|                                                                  |
|  Telegram ---+                                                   |
|  Discord ----+                                                   |
|  WhatsApp ---+                                                   |
|  Slack ------+-->  GATEWAY --> AGENT --> ROUTER --> PROVIDERS     |
|  Signal -----+       |          |                    |           |
|  Matrix -----+  +---------+    |         +-----------+           |
|  CLI --------+  | Session |    |         | Anthropic |           |
|  API/WS -----+  | Manager |    |         | Moonshot  |           |
|                  +---------+    |         | OpenAI    |           |
|                                 |         | xAI       |           |
|                 +---------------+-+       | Groq      |           |
|                 |  COGNITIVE LAYER |       | Ollama    |           |
|                 |  Pulse | Breath  |       | OpenRouter|           |
|                 |  Sleep | Dreams  |       +-----------+           |
|                 +---------+-------+                               |
|                           |                                       |
|                 +---------+-------+                               |
|                 | Skills | Memory |                               |
|                 | Voice  | Affect |                               |
|                 | Scheduler      |                                |
|                 +----------------+                                |
|                                                                   |
+-------------------------------------------------------------------+

git clone https://github.com/tashfeenahmed/scallopbot.git /opt/scallopbot
cd /opt/scallopbot
bash scripts/server-install.sh    # Installs Node 22, PM2, voice deps, Ollama
cp .env.example .env && nano .env
pm2 start ecosystem.config.cjs --env production && pm2 save

The install script is idempotent and sets up:

docker build -t scallopbot .
docker run -d --env-file .env scallopbot

sudo tee /etc/systemd/system/scallopbot.service << EOF
[Unit]
Description=ScallopBot AI Assistant
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/scallopbot
ExecStart=/usr/bin/node /opt/scallopbot/dist/cli.js start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now scallopbot

src/
├── agent/          # Agent loop, session management, crash recovery
├── channels/       # Telegram, Discord, WhatsApp, Slack, Signal, Matrix, CLI, API
├── config/         # Zod-validated configuration schemas
├── dashboard/      # Systemd config generator, crash recovery
├── gateway/        # Server orchestration and channel initialization
├── media/          # PDF, image, URL processing
├── memory/         # Hybrid search, fact extraction, decay engine, profiles
├── proactive/      # Unified scheduler for reminders and triggers
├── providers/      # LLM provider implementations (7 providers)
├── reliability/    # Circuit breaker, graceful degradation
├── routing/        # Cost tracking, complexity analysis, model selection
├── skills/         # Loader, registry, executor, ClawHub client (16 bundled)
├── voice/          # STT (faster-whisper/Groq/OpenAI), TTS (Kokoro/OpenAI)
├── cli.ts          # CLI entry point
└── index.ts        # Library exports

web/                # React + Tailwind + Vite dashboard

npm run dev           # Dev mode with hot reload
npm test              # Run tests (Vitest)
npm run typecheck     # Type check
npm run build         # Production build (compiles TS + builds web dashboard)

ScallopBot's design decisions independently converged on patterns validated by 30 research works from 2023--2026, published at venues including ICLR, NeurIPS, CHI, and ACM TOIS. Key alignments include:

• Hybrid retrieval: Hu et al. (memory survey), Pan et al. (SeCom, ICLR 2025)
• Memory lifecycle: Alqithami (MaRS forgetting benchmark), Yang et al. (graph memory taxonomy)
• Spreading activation: Pavlovic et al. (activation in RAG), Yang et al. (relational dependencies)
• Dream cycles: Zhang (computational account of dreaming)
• Affect modelling: Mozikov et al. (emotional prompting effects), Lu & Li (affective memory)
• Self-reflection: Shinn et al. (Reflexion, 91% HumanEval), Renze & Guven (reflection taxonomy)
• Proactive intelligence: Pasternak et al. (PROBE), Liu et al. (Inner Thoughts)

For the full analysis, see the paper.

MIT

Built by @tashfeenahmed