scallopbot

KO | EN

gitlite — search

#python #javascript #php #machine-learning #java #simulation #midi #docker #markdown #react #csharp #unit-testing

★ 31 Open GitHub ↗

Bio-inspired cognitive architecture for personal AI agents. Memory lifecycle, dream consolidation, affect detection, self-reflection, spreading activation, proactive intelligence. 7 LLM providers, 9 channels, $0.06-0.10/day. OpenClaw-compatible.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">ScallopBot</h1>

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

<a href="Paper2026.pdf">Read the Paper</a>

---

Open-source personal AI agents like [OpenClaw](https://github.com/openclaw/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](https://github.com/snap-research/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:**

| 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), private self-reflection, guarded skill/prompt evolution, 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 Guarded Evolution

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.

### Proactive Intelligence

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.

### Single Outcome Brain

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.

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

### 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](https://github.com/openclaw/openclaw) SKILL.md format. Skills declare their own requirements (binaries, env vars, OS) and are gated at load time. Community skills install from [ClawHub](https://clawhub.ai) with a single CLI command.

### Evidence-Gated Procedural Learning

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](docs/INTELLIGENCE_ROADMAP.md).

### Durable Sub-Agent Orchestration

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.

## 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) | 1 | $0.001 |
| 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

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

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

### Multi-Model Mode (optional)

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:

```bash
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.

### Lifecycle Event Relay (optional)

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

```bash
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.

## 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](https://github.com/ArcadeAI/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](https://typst.app), 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:

```bash
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** | `POST /api/chat`, SSE streaming, session management, file download |
| **WebSocket** | Real-time bidirectional communication with the web dashboard |

## Web Dashboard

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)

## Configuration

Minimal `.env`:

```bash
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:

```bash
COST_DAILY_BUDGET=5.00
COST_MONTHLY_BUDGET=100.00
COST_WARNING_THRESHOLD=0.8
```

Full reference: [.env.example](.env.example)

## Reminders

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

## Error Recovery

| Failure | Response |
|---------|----------|
| Context overflow | Emergency compression -- summarize old messages, keep recent context |
| Auth errors (401/403) | Rotate API keys if multiple are configured |
| Provider outage | Automatic failover to next healthy provider |
| Rate limits | Exponential backoff with jitter |
| Tool crash | RecoveryManager resumes from saved state |
| Process crash | PM2 auto-restart with crash state persistence |

## Architecture

## Comparison with OpenClaw

| Capability | OpenClaw | ScallopBot |
|------------|----------|------------|
| **Memory retrieval** | Vector + FTS5 hybrid | BM25 + semantic + LLM re-ranking |
| **Memory decay** | -- | Natural activation + category half-lives + user-confirmation reinforcement |
| **Memory consolidation** | -- | BFS-clustered fusion + NREM cross-category |
| **Memory forgetting** | -- | Utility-based with soft-archive / hard-prune |
| **Associative retrieval** | -- | Spreading activation with typed edges |
| **Dream cycle** | -- | NREM consolidation + REM exploration |
| **Affect detection** | -- | AFINN-165 + VADER + dual-EMA + affect guard |
| **Self-reflection** | -- | Private composite reflection feeding benchmarked, rollback-capable evolution |
| **Proactive intelligence** | Basic Heartbeat | Gap scanner + inner thoughts + trust feedback loop |
| **Background processing** | Heartbeat wake-up | 3-tier daemon (Pulse / Breath / Sleep) |
| **Cost tracking & budgets** | -- | Built-in per-token tracking with daily/monthly limits |
| **Multi-provider routing** | 2 providers | 7 providers with health-aware failover |
| **Smart model selection** | Manual | Auto-routes by complexity |
| **Local voice (zero cost)** | -- | Kokoro TTS + faster-whisper STT |
| **Skill ecosystem** | 100+ bundled, 3000+ ClawHub | Full OpenClaw SKILL.md compatibility |
| **Channel support** | 15+ platforms | 9 channels |
| **Native apps** | macOS/iOS/Android | -- |

## Deployment

See the [full deployment guide](./DEPLOYMENT.md) or the
[Raspberry Pi notes](./DEPLOYMENT_PI.md) for backup, isolation, rollback and
security guidance. Keep production credentials and operator-specific details
in a private runbook outside the repository.

### One-Command Server Setup (Ubuntu 24.04)

```bash
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:

| Component | Purpose |
|-----------|---------|
| Node.js 24 + PM2 | Runtime and process management |
| Python venv (kokoro-onnx, faster-whisper) | Local voice -- zero API cost TTS/STT |
| Ollama + nomic-embed-text | Local embeddings for semantic memory search |
| ffmpeg + sox | Audio format conversion |

### Alternative: systemd

```bash
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
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `start` | Launch gateway with all configured channels |
| `chat` | Interactive CLI session (`-s <id>` to resume) |
| `config` | Show current configuration (`--json` for machine output) |
| `version` | Show version |
| `skill search <query>` | Search ClawHub |
| `skill install <slug>` | Install from ClawHub |
| `skill uninstall <name>` | Remove a skill |
| `skill list` | List installed skills |
| `skill update [name]` | Update one or all skills |
| `skill-curator status` | Show usage and lifecycle state for agent-created skills |
| `skill-curator run` | Mark stale and archive unused agent-created skills |
| `skill-curator pin <name>` | Keep an agent-created skill active |
| `skill-curator restore <name>` | Restore a recoverably archived skill |
| `migrate run` | Migrate legacy JSONL memories to SQLite |

## Project Structure

```
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
```

## Development

```bash
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)
```

## Research Validation

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](Paper2026.pdf).

## License

MIT

---

Built by <a href="https://github.com/tashfeenahmed">@tashfeenahmed</a>

scallopbot

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README