​

Architecture

​

System Diagram

​

Core Layers

​

Reasoning Plane

1. Receive user intent (text, voice, or hardware event).
2. Load context: memory tiers, identity, session state.
3. Route to an LLM provider via the multi-provider interface.
4. Execute tools selected by the LLM.
5. Store results in memory, update the knowledge graph.
6. Return response — optionally as GenUI SDUI payload.

​

Memory Plane

• Memory Wiki — compiles notes, episodes, and graph entries into durable wiki pages with provenance tracking.
• Session Snapshots — snapshot, branch, and restore full conversation + working memory state.

​

Workflow Plane

• Persist through restarts.
• Support wait (pause until a condition), resume, and cancel.
• Each flow tracks a step timeline with status transitions.
• API: POST /api/taskflows, GET /api/taskflows/{id}, POST /api/taskflows/{id}/resume.

​

Interface Plane (GenUI)

1. A tool returns structured data.
2. The GenUI engine selects an appropriate SDUI template (card, chart, map, form, list).
3. The payload is sent to the client, which renders it without knowing the tool’s internals.

​

Execution Plane

• Tools & Skills — computer use (shell, files, grep), web search, browser automation, custom JSON manifests, Python plugins, WASM sandboxed skills.
• MCP — dual-role: expose FERAL’s tools as an MCP server, and consume external MCP servers.
• Channels — bridge to Telegram, Discord, Slack, WhatsApp.
• HUP (Hardware Use Protocol) — a generic, self-describing hardware hub. Devices declare an actions[] envelope (see HUP_ACTION_SCHEMA in hardware/protocol.py); the brain converts it to a DeviceManifest, registers transport adapters (GenericSelfDescribingAdapter for brain-local USB/serial, WebSocketNodeAdapter for mesh nodes, BridgedPeripheralAdapter for phone-bridged BLE peripherals), and auto-generates LLM tools via GenericHardwareSkill — including a closed-loop honesty loop when capabilities declare a verify contract. Brain-local discovery is config-driven (DEVICE_DISCOVERY_SPECS). Operators can disable the generic path with FERAL_GENERIC_HARDWARE_SKILLS=0 to fall back to hand-written skills.

​

Security

• Blind Vault — API keys stored encrypted, never exposed to the LLM.
• WASM Sandbox — untrusted skills run in a Wasmtime sandbox.
• Permission Plane — tool-level approval policies.

​

Wire Protocol

{
  "type": "text_command | text_response | stream_delta | sdui_payload | telemetry | ...",
  "session_id": "abc-123",
  "payload": { }
}

​

Data Storage

​

Tech Stack