ScallopBot

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). Its insights are stored as assistant-only evidence: they never enter user memory and never rewrite SOUL.md directly. Reusable behavioral or procedural changes must pass the separate evolution pipeline's held-out replay, privacy/safety checks, measured-improvement gate, version ledger, and rollback path.

A gap scanner identifies explicit open loops, approaching deadlines, and stale/blocked work. Passive usage changes such as shorter replies or fewer sessions never justify outreach on their own. Delivery is gated by explicit positive/negative preferences, a configurable proactiveness dial (conservative/moderate/eager), quiet hours, send-time freshness checks, daily limits, and a feedback loop based on actual proactive outcomes rather than general chat frequency.

Generated outreach is realized immediately before delivery using current context and recent message history. Social-quality gates reject internal reasoning, generic check-ins, surveillance language, faux intimacy, pressure, and multi-question interrogations; literal reminders written by the user remain unchanged.

Foreground replies, proactive candidates, scheduled results, sub-agent completions, workflow steps, progress messages, and file deliveries all converge through one shared OutcomeBrain before public delivery or side effects. Producers only propose outcomes; the brain combines the active request with recent conversation, current/relevant user facts and profile state, live board work, live goals, source state, time, provenance, tool observations, evidence, and recent decisions. Stateful foreground answers receive actual final model arbitration; simple no-tool conversation retains a fast deterministic boundary. It can approve, rewrite, suppress, or block, and records only hashed decision receipts—not prompts, messages, tool payloads, or private reasoning. Exact user-authored reminders remain deterministic, while inferred outreach fails closed if final arbitration is unavailable.

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. Recall uses smooth activation from temporal decay, lifecycle, genuine topic relevance, salience, and user confirmation: an old topic fades from general context but can return naturally when it becomes relevant, without magic "history" wording. Automatic retrieval is telemetry only and never reinforces freshness or utility. Assistant self-reflection and agent-subject facts remain separate from user memory. The lifecycle includes 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.

An optional, default-off evolution loop can distill reusable multi-tool workflows into documentation-only skills. Candidates are replayed against held-out tasks, safety and privacy checked, promoted only after a measured improvement, tracked for real use, and automatically rolled back or recoverably archived when they regress or become stale. Machine-authored executable scripts remain blocked without OS isolation. See the intelligence roadmap and reproducible evidence.

Delegated work is tracked in SQLite with atomic batch capacity reservations, lineage, explicit context modes (isolated, brief, fork), bounded orchestrator nesting, progress-aware idle limits, token/cost budgets, and structured acceptance results. Background completions use a leased delivery outbox, survive restarts, update parent context, and reach the user as a concise outcome rather than internal reasoning. Coding tasks can use detached Git worktrees and an implement → independent review/test workflow that returns a conflict-checked patch. The web dashboard includes a live Tasks rail with status, evidence, blockers, hierarchy, logs, and cancellation controls.

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

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

One model serves every purpose by default. If you want specialized models — say, a fine-tuned 4B for memory operations and a different model for the main agent loop — toggle multi-model mode on and register any OpenAI-compatible endpoint under your own name:

MULTI_MODEL_ENABLED=true
CUSTOM_PROVIDER_MY_TOOLS=http://localhost:11434/v1|my-tools-model
CUSTOM_PROVIDER_MY_MEMORY=http://localhost:11434/v1|my-memory-model

# Optional exact token limits for custom/local models
MODEL_TOKEN_LIMITS='{"my_memory":{"contextWindowTokens":262144,"maxOutputTokens":32768}}'

# Optional pricing for paid custom endpoints; local/free custom endpoints stay $0
COST_MODEL_PRICING='{"my_tools/my-tools-model":{"inputPerMillion":0.3,"outputPerMillion":1.8}}'

# Pin background purposes to the memory model...
MODEL_FACT_EXTRACTION=my_memory
MODEL_RERANKER=my_memory
# ...and put the tools model first in the chat fallback chain
PROVIDER_ORDER=my_tools,openrouter

Custom providers behave like built-ins everywhere: they can be pinned per purpose (MODEL_RERANKER, MODEL_FACT_EXTRACTION, MODEL_COGNITION, MODEL_CRITIC, MODEL_EVOLUTION, MODEL_EVAL), placed in PROVIDER_ORDER, and selected with the /model command. With the toggle off, CUSTOM_PROVIDER_* entries are ignored (a warning is logged), so the default single-model setup stays untouched.

Set SCALLOPBOT_EVENT_WEBHOOK_URL to emit key lifecycle events to an external orchestrator:

SCALLOPBOT_EVENT_WEBHOOK_URL=https://orchestrator.example.com/scallopbot/events
SCALLOPBOT_EVENT_WEBHOOK_SECRET=replace-with-shared-secret
SCALLOPBOT_AGENT_ID=scallopbot

The webhook receives POST payloads for memory.consolidation_complete, memory.reflection_output, and session.affect_change. If a secret is set, it is sent as a bearer token.

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
• Delegated Tasks rail with live status, parent/child hierarchy, acceptance evidence, blockers, logs, cancellation, steering, and follow-ups
• 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    |           |
|                       |         |         |           |           |
|                       +--> OUTCOME BRAIN --> delivery/actions     |
|                                 |         | xAI       |           |
|                 +---------------+-+       | Groq      |           |
|                 |  COGNITIVE LAYER |       | Ollama    |           |
|                 |  Pulse | Breath  |       | OpenRouter|           |
|                 |  Sleep | Dreams  |       +-----------+           |
|                 +---------+-------+                               |
|                           |                                       |
|                 +---------+-------+                               |
|                 | Skills | Memory |                               |
|                 | Voice  | Affect |                               |
|                 | Scheduler      |                                |
|                 +----------------+                                |
|                                                                   |
+-------------------------------------------------------------------+

See the full deployment guide or the Raspberry Pi notes for backup, isolation, rollback and security guidance. Keep production credentials and operator-specific details in a private runbook outside the repository.

git clone https://github.com/tashfeenahmed/scallopbot.git /opt/scallopbot
cd /opt/scallopbot
bash scripts/server-install.sh    # Installs Node 24, 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:

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

[Service]
Type=simple
User=scallopbot
Group=scallopbot
WorkingDirectory=/opt/scallopbot
EnvironmentFile=/opt/scallopbot/.env
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)
├── evolution/      # Evidence-gated procedural skill learning and curation
├── goals/          # Persistent, budgeted, verified autonomous goals
├── workflow/       # Context-efficient validated tool DAG execution
├── 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