​

The 15 Runtime Modules

​

How the Brain Works

Wolffish models its runtime after the human brain — not as a metaphor, but as an architecture pattern. Each module handles exactly one cognitive function, and they communicate through a shared event bus (the corpus callosum) rather than calling each other directly. When a message arrives, it flows through the modules like a neural signal:

1. Input arrives — the channel adapter (Desktop, Telegram, or WhatsApp) emits an input.received event on the corpus
2. Context is built — the prefrontal cortex reads your identity files, queries the hippocampus for relevant memories, asks the cerebellum which capabilities are available, and passes everything through the RAS attention filter to fit within the token budget
3. The LLM thinks — the thalamus sends the assembled prompt to the one Brain model you selected (config.llm.brain) and streams the response back; there’s no cascade between providers
4. Response is parsed — Wernicke’s area extracts tool calls and text from the stream, normalizing across all nine cloud provider formats
5. Safety is checked — if tool calls are present, the amygdala checks them against danger patterns and either approves, requests confirmation, or blocks
6. Tools execute — the motor cortex runs approved tools, logging every step to task files with retry logic
7. Response is delivered — Broca’s area streams the final text back to the user through the channel
8. Memory is saved — the hippocampus appends the conversation to today’s episode file
9. Learning happens — the basal ganglia records whether tool calls succeeded or failed, building a feedback history

All of this happens in a deterministic 17-step pipeline. The brainstem runs background processes (file watching, scheduled tasks, nightly memory consolidation), the hypothalamus monitors system health, and the insula provides self-awareness so the agent can report on its own state. The key insight: because every module communicates through events and writes its state to markdown files, the entire brain is observable and editable at every layer.

---

​

Module Reference

Wolffish has 15 runtime modules, each handling one specific function. They all live in src/main/runtime/ and communicate exclusively via the event bus (corpus).

​

corpus.ts — Event Bus

Maps to the corpus callosum. The nervous system connecting all modules. Built on mitt with 30+ typed events. A wildcard handler logs every event to daily markdown files at brain/corpus/YYYY-MM-DD.log.md with a 2-second buffer flush. Old logs are cleaned up after 7 days. Initialized first and passed as a singleton to all other modules.

​

thalamus.ts — Model Gateway

Maps to the thalamus (sensory gateway). Manages nine cloud LLM providers plus Ollama via pure fetch(). Resolves the one Brain model you selected (config.llm.brain) and streams from it — there’s no cascade or automatic substitution between providers. Uses net.isOnline() for instant offline detection. On a transient error it retries the same Brain on a backoff schedule; health tracking with exponential backoff feeds that same-model retry and diagnostics, not provider switching. Exposes a unified async *stream() generator yielding StreamChunk types.

​

prefrontal.ts — Context Builder

Maps to the prefrontal cortex (executive function). The most important module. Reads workspace markdown files, calls cerebellum for tool definitions, calls cortex for memory search, passes candidates through RAS for scoring, and assembles the final system prompt with XML tags. Writes debug snapshots to brain/prefrontal/.debug/. Excludes brain/cerebellum/ and brain/corpus/ from memory candidates.

​

ras.ts — Attention Filter

Maps to the Reticular Activating System. Decides what’s relevant. Keyword-based relevance scoring with a 0.25 minimum threshold. Token budget allocation: 15% identity, 10% prefrontal, 30% memory, 20% skills, 25% history. Uses ~4 chars per token estimation.

​

cortex.ts — Search Index

Maps to the cerebral cortex. Fast retrieval via SQLite. WAL mode, FTS5 virtual table, BM25 ranking. Fully disposable — delete cortex.db and it rebuilds from markdown. Supports single-file index/remove for the brainstem file watcher.

​

hippocampus.ts — Memory

Maps to the hippocampus. Three-tier memory system.

• Episodes (episodes/YYYY-MM-DD.md): Daily conversation logs, appended every turn with no LLM call
• Consolidated (consolidated/YYYY-WNN.md): Weekly summaries generated by brainstem’s nightly compaction
• Knowledge (knowledge/): Permanent topic files promoted from episodes

​

cerebellum.ts — Capability Loader

Maps to the cerebellum (motor coordination). Discovers and loads capabilities. Scans brain/cerebellum/ for capability folders, parses SKILL.md frontmatter (YAML), dynamic-imports plugins, registers tools and danger patterns. Passes PluginContext (pluginDir + workspaceRoot) to plugins on init.

​

wernicke.ts — Response Parser

Maps to Wernicke’s area (language comprehension). Understands LLM output. Parses streaming chunks, extracts tool calls, normalizes across three provider formats into a single ToolCall type. Handles partial JSON and thinking blocks.

​

broca.ts — Response Assembler

Maps to Broca’s area (language production). Produces the final response. Streams tokens to renderer via IPC, formats tool results, manages line breaks between text segments from different LLM turns.

​

amygdala.ts — Safety Gate

Maps to the amygdala (threat detection). Zero hardcoded patterns — all loaded from SKILL.md via cerebellum. Matches against toolName + " " + JSON.stringify(args). Three classification levels: safe (proceed), confirm (show approval dialog), block (deny). IPC approval flow with Promise-based bridge.

​

motor.ts — Task Executor

Maps to the motor cortex. Runs tool calls with full logging. Creates task markdown files at brain/motor/tasks/TASK-{id}.md. Per-step logging with args, output, duration, and attempt count. 3x retry with 2s/6s/18s exponential backoff. AbortController for stop support.

​

basalganglia.ts — Feedback Loop

Maps to the basal ganglia (reward/learning). Learns from outcomes. Daily feedback files with full args and output snippet (~200 char truncation). Records four outcome types: success, failure, denial, approval.

​

hypothalamus.ts — System Monitor

Maps to the hypothalamus (homeostasis). Watches system health. 60-second setInterval monitoring RAM, disk, CPU, and context window usage. Emits health.warning and health.critical events on corpus when thresholds are exceeded.

​

brainstem.ts — Background Processes

Maps to the brainstem (autonomic functions). Runs without user interaction. chokidar file watcher with 500ms debounce triggers cortex reindexing on file changes. node-cron scheduler reads schedules from brainstem/heartbeat.md. Nightly LLM-powered compaction consolidates episodes into weekly summaries (cloud-first for quality). All in-process — no system-level daemons.

​

insula.ts — Self-Awareness

Maps to the insula (interoception). Knows its own state. Exposed via the introspect capability with three tools: wolffish_status, wolffish_performance, wolffish_memory. Reads workspace files directly for stats. Ask Wolffish “how are you doing?” and it reads its own logs to answer.