Luna/Documentation/References/ZeroClaw/Overview.md

ZeroClaw

Overview

ZeroClaw is a lean, trait-driven Rust AI assistant runtime (~1.7k stars, ~1.6k commits). Single binary, <5MB RAM, <10ms startup. Everything is a swappable trait. Repo: https://github.com/openagen/zeroclaw

Architecture

• Single-binary Rust runtime — no microservices, no plugins to install
• Trait-driven design: every subsystem (Provider, Channel, Tool, Memory, Runtime, Security) is a trait you swap
• Minimal footprint: <5MB RAM, <10ms cold start
• All features compiled in-process, zero external dependencies for core functionality

Providers

15+ provider implementations behind a Provider trait: OpenAI, Anthropic, Gemini, Ollama, OpenRouter, Azure OpenAI, AWS Bedrock, GitHub Copilot, GLM, Telnyx, llama.cpp, vLLM, custom endpoints.

Key pattern — ReliableProvider wrapper: wraps any provider with automatic fallback chains and retry logic. If primary fails, falls through to secondary, tertiary, etc.

// Provider trait (src/providers/traits.rs)
pub trait Provider: Send + Sync {
    fn name(&self) -> &str;
    async fn chat(&self, request: ChatRequest) -> Result<ChatResponse>;
    async fn stream(&self, request: ChatRequest) -> Result<Box<dyn Stream<Item = Result<ChatChunk>>>>;
}

Agent Loop

• Full tool-calling protocol: LLM requests tool call → agent executes tool → feeds result back → loops until LLM stops requesting tools
• DelegateTool: spawns a sub-agent with a scoped task for multi-agent delegation
• Memory injection into agent context
• Identity/persona system supporting AIEOS v1.1 JSON format and OpenClaw markdown format

Channels

26 channel implementations behind a Channel trait: CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp (Web + Business API), Email, IRC, Lark, DingTalk, QQ, Nostr, MQTT, Webhook, and more.

// Channel message types (src/channels/traits.rs)
pub struct ChannelMessage {
    pub id: String,
    pub sender: String,
    pub reply_target: Option<String>,
    pub content: String,
    pub channel: String,
    pub timestamp: DateTime<Utc>,
    pub thread_ts: Option<String>,
}

Memory

6 backends behind a Memory trait:

• SQLite: hybrid FTS5 full-text + cosine vector similarity in a single query, zero external deps
• PostgreSQL
• Lucid bridge
• Markdown (file-based)
• Qdrant (vector DB)
• Explicit none

pub trait Memory: Send + Sync {
    fn name(&self) -> &str;
    async fn store(&self, entry: MemoryEntry) -> Result<()>;
    async fn recall(&self, query: &str, limit: usize) -> Result<Vec<MemoryEntry>>;
}

pub struct MemoryEntry {
    pub id: String,
    pub key: String,
    pub content: String,
    pub category: MemoryCategory,
    pub timestamp: DateTime<Utc>,
    pub session_id: Option<String>,
    pub score: Option<f64>,
}

pub enum MemoryCategory {
    Core,
    Daily,
    Conversation,
    Custom(String),
}

Custom embedding provider routing — memory backends can use different embedding models.

Tools

42+ tool implementations behind a Tool trait:

// Tool trait (src/tools/traits.rs)
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> Result<ToolResult>;
}

Tool categories:

• Shell & Files: shell execution, file read/write/edit, glob search, content search
• Browser & Web: browser automation, HTTP requests, web fetch/search, screenshots
• Documents: PDF read, image info
• Git: git operations (status, diff, commit, log, etc.)
• Scheduling: cron add/list/remove/update/run
• Memory: store/recall/forget (tools that interact with the Memory trait)
• Delegation: DelegateTool for sub-agent spawning
• Hardware: USB discover/introspect, robot-kit integration
• Integration: Composio (1000+ OAuth apps), SOP tools, Pushover notifications

Sessions

• Per-sender conversation history
• Compaction (summarization of old messages)
• Autosave thresholds (every N messages, not just on shutdown)
• Per-sender provider/model overrides (each conversation can use a different model)

Security

Comprehensive security stack (16 modules):

• SecurityPolicy: Autonomy levels — readonly, supervised, full
• Workspace Scoping: Operations restricted to declared workspace paths
• Filesystem Guards: 14 system directories blocked, symlink escape detection, null byte injection blocked
• Sandboxing: Landlock, Bubblewrap, Docker, Firejail — multiple isolation backends
• Gateway Pairing: 6-digit codes + bearer tokens for channel authentication
• Encrypted Secrets: SecretStore for API keys and credentials
• Audit Logging: All security-relevant actions logged
• Emergency Stop: EstopManager for immediate agent shutdown
• Prompt Guard: Detection of prompt injection attempts
• Leak Detector: Prevents secrets from appearing in agent output
• OTP: One-time password support

Runtime

RuntimeAdapter trait with two implementations:

• NativeRuntime: Direct execution on host OS
• DockerRuntime: Isolated execution in Docker containers Tool execution can be routed through either runtime for isolation.

Skills

• TOML manifests (SKILL.toml) + SKILL.md instructions
• open-skills sync for community skill repositories
• Security audit on install: blocks symlinks, scripts, unsafe patterns

Configuration

• TOML-based config at ~/.zeroclaw/config.toml
• Hot-reload on key fields without restart
• Per-channel, per-provider, per-tool configuration sections

Tunnel

Trait-based tunneling for exposing local instance to the internet:

• Cloudflare Tunnel
• Tailscale
• ngrok
• Custom tunnel implementations

---

In-Depth Reference Pages

• ReliableProvider — Three-level failover (model chain, provider chain, retry loop), error classification, API key rotation
• Agent Loop & Tools — Tool trait, agent execution loop, tool serialization, credential scrubbing
• Memory — Memory trait, SQLite hybrid FTS5+vector search, embedding cache, 6 backends
• Channel Messages — Channel trait, draft update protocol, ChannelMessage struct, SendMessage builder
• Security — SecurityPolicy, autonomy levels, command allowlist, path validation, sandboxing, secret store, e-stop
• Sessions — Per-sender storage, compaction logic, autosave thresholds, per-sender overrides
• Configuration — TOML config struct (30+ sections), ModelProviderConfig, DelegateAgentConfig, hot-reload
• Runtime Adapters — RuntimeAdapter trait, NativeRuntime vs DockerRuntime, capability querying
• Skills — SKILL.toml manifest, security audit on install, open-skills sync, prompt injection
• Compaction Strategy — Proactive agent-side and reactive channel-side compaction, summarization prompts, helper functions

---

Relevance to Luna

Patterns Worth Adopting

ZeroClaw is architecturally closest to Luna (monolithic binary, trait/interface-driven design). These patterns map directly:

• ReliableProvider wrapper: Luna's IProvider returning IChatClient is clean. Add a decorator that wraps any IProvider with fallback chains and retry logic. See ReliableProvider for the three-level failover pattern. Link to Core.
• Tool trait + Agent loop: This is Luna's #1 gap. The Tool trait maps cleanly to a C# ITool interface. The agent loop is the missing piece that turns Luna from a chat relay into an assistant. See Agent Loop & Tools. Link to Skills.
• Memory with hybrid search: Luna's IMemoryStore exists but has no recall. ZeroClaw's SQLite memory does hybrid FTS5 + cosine vector similarity in one query. See Memory. Link to Luna's Memory.
• Channel message normalization: The ChannelMessage struct should be the baseline for Luna's DTO. The draft update protocol maps to SignalR. See Channel Messages. Link to Channels.
• Session autosave + per-sender overrides: Autosave every N messages for crash resilience. Per-sender model overrides are cheap to add. See Sessions. Link to Core.
• Compaction: Dual-path approach (proactive message-count + reactive overflow recovery) with structured summarization prompts. See Compaction Strategy.
• Security fundamentals: Before tool execution, Luna needs filesystem guards, workspace scoping, and autonomy levels. See Security. ZeroClaw's SecurityPolicy is the reference.
• TOML config with hot-reload: Luna's Configuration module plans this. ZeroClaw's per-subsystem section pattern is the target. See Configuration.
• Runtime adapters: When tool execution is added, a similar IRuntimeAdapter allows switching between native and Docker. See Runtime Adapters.
• Skills system: SKILL.toml manifest with security audit on install. See Skills.

Key Differences from Luna

• Rust vs .NET/C# — different ecosystem, but the trait-driven architecture maps well to C# interfaces
• ZeroClaw has 42+ tools; Luna has 0 — tool system is the critical gap
• ZeroClaw has 15+ providers; Luna has 2 (Mistral, Ollama)
• ZeroClaw has 26 channels; Luna has 1 (CLI)
• ZeroClaw has comprehensive security (16 modules); Luna has none
• ZeroClaw runs as a single <5MB binary; Luna's .NET runtime is heavier but offers richer DI/middleware ecosystem