Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wolffi.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Brain Modules

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 — Provider Cascade

Maps to the thalamus (sensory gateway). Manages three LLM providers via pure fetch(). Implements health tracking with exponential backoff. Uses net.isOnline() for instant offline detection. Exposes a unified async *stream() generator yielding StreamChunk types. Cascade order: Claude → OpenAI → Ollama.

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