Project architecture

System overview

The repo follows an “example app + shared components” layout: application/edge_agent is a buildable ESP-IDF sample that wires Wi-Fi, the config UI, Lua modules, and capabilities into a full device; components holds reusable runtime core, capability plugins, and hardware/script extensions for other boards and scenarios.

Today the code falls into four areas:

App assembly: main and common — boot, networking, settings, the HTTP provisioning UI, and app-level module registration.
Capabilities: claw_capabilities — outward-facing capabilities such as IM, MCP client/server, Lua runtime, scheduling, files, time, web search, and more.
Runtime core: claw_modules — Agent infrastructure: core context, capability registration, event routing, memory, and skills.
Device & script extensions: lua_modules — exposes displays, cameras, audio, buttons, GPIO, PWM, storage, and other peripherals to Lua and the Agent.

Project directory layout

Directoryapplication/edge_agent/ Demo app — wires the framework and caps into flashable firmware
- Directorymain/ Boot entry (app_main)
  - main.c Firmware entry
- Directorycomponents/ App-level components
  - Directoryapp_config/ Configuration persistence (NVS read/write)
    …
  - Directoryhttp_server/ Web management UI and JSON API
    …
  - Directorycmd_wifi/ Wi-Fi CLI commands
    …
  - Directorygen_bmgr_codes/ [auto-generated] board-adaptation helper code
    …
- Directoryfatfs_image/ Factory FATFS inputs: router_rules, memory, scheduler, static files, and app-bundled Skills
  - …
Directorycomponents/common/ Shared app components — reusable wiring across apps
- Directoryapp_claw/ App startup and wiring (app_claw_start, CLI, Lua module registration)
  - …
- Directorywifi_manager/ Wi-Fi and network setup
  - …
- Directorysettings/ Base library for local settings persistence
  - …
- Directorycaptive_dns/ Captive DNS for SoftAP provisioning
  - …
- Directorydisplay_arbiter/ Display ownership arbitration [details]
  - …
- Directoryemote/ Emote display and network-state linkage
  - …
- Directoryesp_painter/ Lightweight drawing helpers
  - …
- Directoryesp_video/ Video-processing wrappers
  - …
- Directoryhttp_reuse/ Reusable HTTP foundation component
  - …
- Directorylua_module_builder/ Lua module build helpers
  - …
- Directoryskill_builder/ Skill build helpers
  - …
Directorycomponents/
- Directoryclaw_modules/ Runtime core
  - Directoryclaw_core/ Agent core — Agent loop, context assembly, tool calls
    …
  - Directoryclaw_cap/ Capability runtime — capability abstraction, registration, and management
    …
  - Directoryclaw_event_router/ Event Router & automation — deterministic event routing
    …
  - Directoryclaw_memory/ Structured memory
    …
  - Directoryclaw_ramfs/ RAMFS runtime filesystem support
    …
  - Directoryclaw_skill/ Skills — skill metadata and loading
    …
- Directoryclaw_capabilities/ Capability
  - Directorycap_im_platform/ Unified IM platform component (Feishu, QQ, Telegram, WeChat groups)
    …
  - Directorycap_mcp_*/ MCP protocol (MCP client, MCP server)
    …
  - Directorycap_lua/ Lua runtime management
    …
  - Directorycap_skill_mgr/ Managed interface wrapper for claw_skill
    …
  - Directorycap_scheduler/ Scheduler
    …
  - Directorycap_router_mgr/ Managed interface wrapper for claw_event_router
    …
  - … other utility capabilities
- Directorylua_modules/ Device & script extensions
  - Directorylua_module_display/ Display
    …
  - Directorylua_module_camera/ Camera
    …
  - Directorylua_module_audio/ Audio
    …
  - Directorylua_driver_mcpwm/ PWM
    …
  - Directorylua_driver_pcnt/ Pulse counter
    …
  - Directorylua_module_button/ Button
    …
  - Directorylua_driver_gpio/ GPIO
    …
  - Directorylua_driver_i2c/ I2C bus
    …
  - Directorylua_driver_touch/ Touch
    …
  - Directorylua_driver_adc/ ADC sampling
    …
  - Directorylua_module_led_strip/ LED strip
    …
  - Directorylua_module_storage/ Storage
    …
  - Directorylua_module_delay/ Delays
    …
  - Directorylua_module_system/ System time, memory, and network status
    …
  - Directorylua_module_event_publisher/ Event publishing
    …
  - Directorylua_driver_uart/ UART serial I/O
    …
  - Directorylua_module_ble_hid/ Bluetooth HID
    …
  - Directorylua_module_board_manager/ Board management
    …
  - Directorylua_module_call_capability/ Capability call bridge
    …
  - Directorylua_module_environmental_sensor/ Environmental sensor
    …
  - Directorylua_module_fuel_gauge/ Fuel gauge
    …
  - Directorylua_module_http_server/ Local HTTP server
    …
  - Directorylua_module_image/ Image processing
    …
  - Directorylua_module_imu/ IMU sensor
    …
  - Directorylua_module_ir/ Infrared
    …
  - Directorylua_module_json/ JSON utilities
    …
  - Directorylua_module_knob/ Knob
    …
  - Directorylua_module_lcd/ LCD
    …
  - Directorylua_module_lcd_touch/ LCD touch
    …
  - Directorylua_module_lvgl/ LVGL UI
    …
  - Directorylua_module_magnetometer/ Magnetometer
    …
  - Directorylua_module_sci/ Serial peripheral integration
    …
  - Directorylua_module_thread/ Thread support
    …
  - Directorylua_module_vision/ Vision capabilities
    …
Directorydocs/ Project documentation and images
- …

Runtime diagram

Runtime data directory

All runtime data lives under the FATFS mount /fatfs:

Directoryfatfs/
- Directorysessions/ Session history (one file per session id)
  - …
- Directorymemory/
  - MEMORY.md Human-readable memory view (read-only)
  - memory_records.jsonl Structured memory records
  - memory_index.json Summary-tag and keyword index
  - memory_digest.log Memory-operation digest log
  - user.md User profile
  - soul.md Persona
  - identity.md Identity
- Directoryskills/
  - Directoryskill_id/
    SKILL.md Skill metadata and body
    Directoryscripts/ Skill-bundled scripts (optional)
    …
- Directoryscripts/
  - Directorybuiltin/ Built-in Lua test scripts and libraries
    …
  - Directorydocs/ Built-in Lua module docs
    …
  - *.lua Custom Lua scripts
- Directoryrouter_rules/
  - router_rules.json Automation rules
- Directoryscheduler/
  - schedules.json Scheduler jobs
  - schedules.json.state Scheduler runtime state (generated)
- Directorystatic/
  - ESP-Claw.png Example static asset (factory preset)
- Directoryinbox/
  - … IM attachments

Backup and reset

Backup: copy the /fatfs subfolders (sessions/, memory/, skills/, scripts/, router_rules/, scheduler/, static/, inbox/) to external storage.
Reset: re-flash the storage partition or re-flash the full firmware.