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.

```rust
// 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.

```rust
// 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

```rust (src/memory/traits.rs)
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:

```rust
// 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