nerve/.knowledge/architecture.md

Nerve Architecture

Observation engine for autonomous agents — sense the world, react to changes, run workflows.

Core Pipeline

External World → Sense → Signal → Workflow → Log
                           ↑
                     compute() returns
                     { signal, workflow }

Causality is one-directional. Logs are the end of the chain — they cannot trigger further Senses (prevents feedback loops).

Two Extension Points

Extension	Question	Nature
Sense	What to observe & when to react	compute() pure function + YAML config (interval / on)
Workflow	What to do	Roles + Moderator

Senses own both the "what" (compute logic) and the "when" (config-driven scheduling). A Sense can trigger a Workflow directly by returning { signal, workflow: { name, prompt } }.

Two Event Types

• Signal — from Sense compute (non-null return). Pure fact, no intent. Drives the front half (perception).
• Command Event — inside Workflow Threads. Has causal chain, must be responded to. Drives the back half (action).

Process Isolation

• One worker per Sense group (long-lived)
• One worker per Workflow type (on-demand)
• Workers never talk to each other
• All user code runs in isolated Workers; kernel never loads user code directly

Storage Systems

• Log Store — SQLite with WAL mode for audit trails and workflow state
• Sense Databases — Isolated SQLite per sense group for private data
• Knowledge Store — Vector search index for project context
• Blob Store — Content-addressable storage for large artifacts

Signal Flow

Sense compute outputs are routed through signal routing logic that determines whether to emit a signal or trigger a workflow—never both simultaneously.