Project architecture

System overview

The repo follows an “example app + shared components” layout: application/basic_demo 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: application/basic_demo/main — boot, networking, settings, the HTTP provisioning UI, and demo-level module registration.
Capabilities: components/claw_capabilities — outward-facing capabilities such as IM, MCP client/server, Lua runtime, scheduling, files, time, web search, and more.
Runtime core: components/claw_modules — Agent infrastructure: core context, capability registration, event routing, memory, and skills.
Device & script extensions: components/lua_modules — exposes displays, cameras, audio, buttons, GPIO, PWM, storage, and other peripherals to Lua and the Agent.

Project directory layout

Directoryapplication/basic_demo/ Demo app — wires the framework and caps into flashable firmware
- Directorymain/ Boot, Wi‑Fi, HTTP config UI, app_claw_start
  - main.c Firmware entry
  - app_claw.c App bootstrapping and wiring
  - app_expression_emote.* Emote display and network-state linkage
  - basic_demo_wifi.* Wi-Fi and network setup
  - basic_demo_settings.* Local settings persistence
  - config_http_server.* Web configuration service
  - basic_demo_lua_modules.* Lua module registration
  - Directoryweb/ Device configuration frontend assets
    …
- Directorycomponents/display_arbiter/ Display ownership arbitration [details]
  - …
- Directoryfatfs_image/ Factory FATFS: skills, router_rules, memory, scripts samples
  - …
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_skill/ Skills — skill metadata and loading
    …
- Directoryclaw_capabilities/ Capability
  - Directorycap_im_*/ IM (Feishu, QQ, Telegram, WeChat)
    …
  - 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_module_mcpwm/ PWM
    …
  - Directorylua_module_button/ Button
    …
  - Directorylua_module_gpio/ GPIO
    …
  - 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
    …
  - Directoryesp_painter/ Lightweight drawing helpers
    …
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/
  - skills_list.json Skills manifest (id, file, summary, cap_groups)
  - *.md Skill documents
- Directoryscripts/
  - hello.lua Factory sample script
  - audio_fft_2.lua Audio capture and spectrum-analysis sample
  - mcpwm_servo.lua Servo PWM control sample
  - *.lua Custom Lua scripts
- Directoryrouter_rules/
  - router_rules.json Automation rules
- Directoryscheduler/
  - schedules.json Scheduler jobs
  - schedules.json.state Scheduler runtime state (generated)
- Directoryinbox/
  - … IM attachments

Backup and reset

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