MoonHub

MoonHub

[!NOTE] Acknowledgments

This project was inspired by the feature integration of TinyClaw and the lightweight design of PicoClaw, and continues to develop in its own unique direction.

Documentation Index (plugins, learning, compactor, SHIELD, memory, delegation, etc.): docs/README.md.

Changelog: CHANGELOG.md — Project updates and release notes

Companion App: ../MoonHub-PWA/README.md — installable PWA for pairing, chat, Space, and settings

中文文档

Introduction

Your AI assistant — instant, alive, connected.

MoonHub is an AI assistant that works out of the box. No technical background needed — plug in, pair, and start talking. Your data stays on your device. Your AI adapts to you.

Design Philosophy

Core Features

🤖 Agent Social Network

Agents can add each other as friends — just like adding a contact in any messaging app. Send a friend request, get approved, and now your agents can talk. You decide what's shared and what stays private. Each Agent has a cryptographic identity, and communication is encrypted end-to-end. It's like building your own AI social circle.

• Friend System — Send requests, accept or reject, revoke when needed. Your agent only talks to agents you trust.
• Zone-based Access Control — Three-tier data architecture: Private (only you), Shared (friends can read), Public (anyone can read). You decide what each friend can see.
• Local-first, Cloud-optional — Agents on the same network connect directly. Need to reach someone across the internet? An optional cloud relay bridges the gap — no port forwarding required.

[!IMPORTANT] The agent social network is under active development. Friend management and zone-based access control are implemented. Task delegation and file transfer between agents are defined in the protocol but not yet available in handlers. Stay tuned for updates.

🎨 Dynamic UI Generation

Say goodbye to traditional Agents that "only output text." MoonHub can generate visual interactive interfaces in real-time based on your needs — financial dashboards, task managers, data visualizations — everything adapts on demand. You describe the idea, the Agent builds it for you.

📱 Dedicated Application

Users interact with the device through a dedicated app. Currently provided as a PWA for quick installation and offline use; native mobile apps are coming soon to cover more platforms and use cases. Frontend repo: ../MoonHub-PWA/README.md.

What Can You Do?

MoonHub adapts to your life, not the other way around. Here are some ways people use it:

Your imagination is MoonHub's only boundary.

Quick Start

1. Power On — Device automatically creates a WiFi hotspot (MoonHub-XXXX)
2. Configure Network — Connect to the hotspot, access the setup page, configure WiFi and set authorization code
3. Install PWA — After configuration, follow the guide to install the PWA app
4. Start Using — PWA automatically scans for local devices, enter the authorization code to start chatting, managing, and configuring

Features

Implemented

• Adaptive Memory — 3-layer memory system (episodic, semantic FTS5, temporal decay) that learns what to remember and forget over time.
• Self-Improving — Behavioral pattern detection system that learns from user feedback, tracks tool usage preferences, and evolves patterns over time.
• Plugin Architecture — Channels, providers, and tools are all plugins. The core stays tiny — everything else is extensible.
• Context Compactor — 4-layer context compaction pipeline (rules, dedup, LLM summary, L0/L1/L2 tiers) integrated in the agent loop; see docs/implementation/compactor-status.md and pkg/compactor/docs/.
• SHIELD.md Anti-Malware — Runtime threat evaluation engine with YAML threat parsing, pattern matching, approval workflow, and 8 built-in threats; see docs/implementation/shield-status.md and pkg/shield/docs/.
• Delegation System — Sub-agent orchestration (non-blocking and background tasks, template reuse, adaptive timeouts, SQLite persistence, Intercom pub/sub). Opt-in via delegation.enabled in config.json (default off); see pkg/delegation/docs/README.md, pkg/delegation/docs/CONFIG.md, and docs/implementation/delegation-status.md.
• Inter-Agent Comms (Intercom) — In-process pub/sub for delegation-time signals: subscribe per topic (On), catch-all via OnAny, bounded per-topic retention with Recent / RecentAll; see pkg/delegation/intercom.go and the Intercom section in docs/implementation/delegation-status.md.
• Smart Router V2 — 4-tier model routing system (simple/moderate/complex/reasoning) with rule-based scoring, feature extraction, and privacy-safe metrics. Routes simple queries to cheap models and complex ones to powerful models; see pkg/routing/docs/README.md and docs/implementation/routing-status.md.
• Device Provisioning — Zero-config WiFi setup (hotspot, scan/connect, diagnostics, automatic and manual recovery, factory reset, auth code, SSE). Opt-in on the web launcher via MOONHUB_PROVISIONING_ENABLED=1; includes React provisioning wizard and optional PWA offline cache for that flow. See pkg/provisioning/docs/README.md, pkg/provisioning/docs/CONFIG.md, and docs/implementation/provisioning-status.md.
• Cloud directory & relay — Optional HTTP directory (PostgreSQL + Redis) for agent registration and online relay endpoints, plus a WebSocket relay with directory-backed Ed25519 auth; device-side pkg/transport CloudClient and Resolver (LAN-first, then cloud). See docs/implementation/cloud-directory-relay-status.md, cloud/directory/docs/README.md, cloud/relay/docs/README.md, and pkg/transport/docs/README.md.
• MoonHub PWA (companion app) — Installable progressive web app for LAN discovery, pairing, chat, Space, and settings; uses backend APIs such as GET /api/discover, GET /api/devices, and channel CRUD on /api/channels. Backend contract: web/backend/api/README.md. Frontend docs (split layout): MoonHub-PWA/docs/README.md.
• Dynamic tools (AI-generated UI) — Schema-driven tools persisted in SQLite (dynamic_tools.db), generated via LLM from natural language, executed server-side with optional HTTP fetch injection, exposed as LAN /api/dynamic-tools; PWA renders with DynamicRenderer and chat/space dynamic components. See pkg/dynamictools/docs/README.md, docs/implementation/dynamic-tools-status.md, and web/backend/api/README.md.
• Agent Social Network — Friend management (request/accept/reject/revoke) with Ed25519 cryptographic identity, MHP (MoonHub Protocol) envelope messaging, LAN-direct and cloud-relay transport, and 3-tier zone-based access control (Privacy/Shared/Public). See pkg/friends/, pkg/protocol/mhp/, pkg/zones/, and pkg/transport/.

Planned

• Wasm tool engine — Execute engine: wasm dynamic tools (wazero or equivalent); schema path is already shipped
• Cross-agent task delegation — Delegate tasks to friend agents via MHP protocol (types defined, handlers in progress)
• Cross-agent file transfer — Send files between friend agents with zone-based access checks (types defined, handlers in progress)
• Native APP — Native mobile applications for iOS and Android platforms