feat: enhance agent personality, tool guidance, and memory hygiene
- Expand communication style presets (professional, expressive, custom) - Enrich SOUL.md with human-like tone and emoji-awareness guidance - Add crash recovery and sub-task scoping guidance to AGENTS.md scaffold - Add 'Use when / Don't use when' guidance to TOOLS.md and runtime prompts - Implement memory hygiene system with configurable archiving and retention - Add MemoryConfig options: hygiene_enabled, archive_after_days, purge_after_days, conversation_retention_days - Archive old daily memory and session files to archive subdirectories - Purge old archives and prune stale SQLite conversation rows - Add comprehensive tests for new features
This commit is contained in:
argenis de la rosa
parent
f4f180ac41
commit
ec2d5cc93d
29 changed files with 3600 additions and 116 deletions
93
README.md
93
README.md
|
|
@ -12,12 +12,19 @@
|
|||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
|
||||
</p>
|
||||
|
||||
The fastest, smallest, fully autonomous AI assistant — deploy anywhere, swap anything.
|
||||
Fast, small, and fully autonomous AI assistant infrastructure — deploy anywhere, swap anything.
|
||||
|
||||
```
|
||||
~3.4MB binary · <10ms startup · 1,017 tests · 22+ providers · 8 traits · Pluggable everything
|
||||
```
|
||||
|
||||
### Why teams pick ZeroClaw
|
||||
|
||||
- **Lean by default:** small Rust binary, fast startup, low memory footprint.
|
||||
- **Secure by design:** pairing, strict sandboxing, explicit allowlists, workspace scoping.
|
||||
- **Fully swappable:** core systems are traits (providers, channels, tools, memory, tunnels).
|
||||
- **No lock-in:** OpenAI-compatible provider support + pluggable custom endpoints.
|
||||
|
||||
## Benchmark Snapshot (ZeroClaw vs OpenClaw)
|
||||
|
||||
Local machine quick benchmark (macOS arm64, Feb 2026), same host, 3 runs each.
|
||||
|
|
@ -30,7 +37,17 @@ Local machine quick benchmark (macOS arm64, Feb 2026), same host, 3 runs each.
|
|||
| `--help` max RSS observed | **~7.3 MB** | **~394 MB** |
|
||||
| `status` max RSS observed | **~7.8 MB** | **~1.52 GB** |
|
||||
|
||||
> Notes: measured with `/usr/bin/time -l`; first run includes cold-start effects. OpenClaw results include `pnpm install` + `pnpm build` before execution.
|
||||
> Notes: measured with `/usr/bin/time -l`; first run includes cold-start effects. OpenClaw results were measured after `pnpm install` + `pnpm build`.
|
||||
|
||||
Reproduce ZeroClaw numbers locally:
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -38,34 +55,48 @@ Local machine quick benchmark (macOS arm64, Feb 2026), same host, 3 runs each.
|
|||
git clone https://github.com/theonlyhennygod/zeroclaw.git
|
||||
cd zeroclaw
|
||||
cargo build --release
|
||||
cargo install --path . --force
|
||||
|
||||
# Quick setup (no prompts)
|
||||
cargo run --release -- onboard --api-key sk-... --provider openrouter
|
||||
zeroclaw onboard --api-key sk-... --provider openrouter
|
||||
|
||||
# Or interactive wizard
|
||||
cargo run --release -- onboard --interactive
|
||||
zeroclaw onboard --interactive
|
||||
|
||||
# Or quickly repair channels/allowlists only
|
||||
zeroclaw onboard --channels-only
|
||||
|
||||
# Chat
|
||||
cargo run --release -- agent -m "Hello, ZeroClaw!"
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
cargo run --release -- agent
|
||||
zeroclaw agent
|
||||
|
||||
# Start the gateway (webhook server)
|
||||
cargo run --release -- gateway # default: 127.0.0.1:8080
|
||||
cargo run --release -- gateway --port 0 # random port (security hardened)
|
||||
zeroclaw gateway # default: 127.0.0.1:8080
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Start full autonomous runtime
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
cargo run --release -- status
|
||||
zeroclaw status
|
||||
|
||||
# Run system diagnostics
|
||||
zeroclaw doctor
|
||||
|
||||
# Check channel health
|
||||
cargo run --release -- channel doctor
|
||||
zeroclaw channel doctor
|
||||
|
||||
# Get integration setup details
|
||||
cargo run --release -- integrations info Telegram
|
||||
zeroclaw integrations info Telegram
|
||||
|
||||
# Manage background service
|
||||
zeroclaw service install
|
||||
zeroclaw service status
|
||||
```
|
||||
|
||||
> **Tip:** Run `cargo install --path .` to install `zeroclaw` globally, then use `zeroclaw` instead of `cargo run --release --`.
|
||||
> **Dev fallback (no global install):** prefix commands with `cargo run --release --` (example: `cargo run --release -- status`).
|
||||
|
||||
## Architecture
|
||||
|
||||
|
|
@ -82,13 +113,20 @@ Every subsystem is a **trait** — swap implementations with a config change, ze
|
|||
| **Memory** | `Memory` | SQLite with hybrid search (FTS5 + vector cosine similarity), Markdown | Any persistence backend |
|
||||
| **Tools** | `Tool` | shell, file_read, file_write, memory_store, memory_recall, memory_forget, browser_open (Brave + allowlist), composio (optional) | Any capability |
|
||||
| **Observability** | `Observer` | Noop, Log, Multi | Prometheus, OTel |
|
||||
| **Runtime** | `RuntimeAdapter` | Native (Mac/Linux/Pi) | Docker, WASM |
|
||||
| **Runtime** | `RuntimeAdapter` | Native (Mac/Linux/Pi) | Docker, WASM (planned; unsupported kinds fail fast) |
|
||||
| **Security** | `SecurityPolicy` | Gateway pairing, sandbox, allowlists, rate limits, filesystem scoping, encrypted secrets | — |
|
||||
| **Tunnel** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | Any tunnel binary |
|
||||
| **Heartbeat** | Engine | HEARTBEAT.md periodic tasks | — |
|
||||
| **Skills** | Loader | TOML manifests + SKILL.md instructions | Community skill packs |
|
||||
| **Integrations** | Registry | 50+ integrations across 9 categories | Plugin system |
|
||||
|
||||
### Runtime support (current)
|
||||
|
||||
- ✅ Supported today: `runtime.kind = "native"`
|
||||
- 🚧 Planned, not implemented yet: Docker / WASM / edge runtimes
|
||||
|
||||
When an unsupported `runtime.kind` is configured, ZeroClaw now exits with a clear error instead of silently falling back to native.
|
||||
|
||||
### Memory System (Full-Stack Search Engine)
|
||||
|
||||
All custom, zero external dependencies — no Pinecone, no Elasticsearch, no LangChain:
|
||||
|
|
@ -124,7 +162,7 @@ ZeroClaw enforces security at **every layer** — not just the sandbox. It passe
|
|||
|---|------|--------|-----|
|
||||
| 1 | **Gateway not publicly exposed** | ✅ | Binds `127.0.0.1` by default. Refuses `0.0.0.0` without tunnel or explicit `allow_public_bind = true`. |
|
||||
| 2 | **Pairing required** | ✅ | 6-digit one-time code on startup. Exchange via `POST /pair` for bearer token. All `/webhook` requests require `Authorization: Bearer <token>`. |
|
||||
| 3 | **Filesystem scoped (no /)** | ✅ | `workspace_only = true` by default. 14 system dirs + 4 sensitive dotfiles blocked. Null byte injection blocked. Symlink escape detection via canonicalization. |
|
||||
| 3 | **Filesystem scoped (no /)** | ✅ | `workspace_only = true` by default. 14 system dirs + 4 sensitive dotfiles blocked. Null byte injection blocked. Symlink escape detection via canonicalization + resolved-path workspace checks in file read/write tools. |
|
||||
| 4 | **Access via tunnel only** | ✅ | Gateway refuses public bind without active tunnel. Supports Tailscale, Cloudflare, ngrok, or any custom tunnel. |
|
||||
|
||||
> **Run your own nmap:** `nmap -p 1-65535 <your-host>` — ZeroClaw binds to localhost only, so nothing is exposed unless you explicitly configure a tunnel.
|
||||
|
|
@ -139,6 +177,26 @@ Inbound sender policy is now consistent:
|
|||
|
||||
This keeps accidental exposure low by default.
|
||||
|
||||
Recommended low-friction setup (secure + fast):
|
||||
|
||||
- **Telegram:** allowlist your own `@username` (without `@`) and/or your numeric Telegram user ID.
|
||||
- **Discord:** allowlist your own Discord user ID.
|
||||
- **Slack:** allowlist your own Slack member ID (usually starts with `U`).
|
||||
- Use `"*"` only for temporary open testing.
|
||||
|
||||
If you're not sure which identity to use:
|
||||
|
||||
1. Start channels and send one message to your bot.
|
||||
2. Read the warning log to see the exact sender identity.
|
||||
3. Add that value to the allowlist and rerun channels-only setup.
|
||||
|
||||
If you hit authorization warnings in logs (for example: `ignoring message from unauthorized user`),
|
||||
rerun channel setup only:
|
||||
|
||||
```bash
|
||||
zeroclaw onboard --channels-only
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config: `~/.zeroclaw/config.toml` (created by `onboard`)
|
||||
|
|
@ -166,6 +224,9 @@ workspace_only = true # default: true — scoped to workspace
|
|||
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]
|
||||
forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]
|
||||
|
||||
[runtime]
|
||||
kind = "native" # only supported value right now; unsupported kinds fail fast
|
||||
|
||||
[heartbeat]
|
||||
enabled = false
|
||||
interval_minutes = 30
|
||||
|
|
@ -198,10 +259,14 @@ enabled = false # opt-in: 1000+ OAuth apps via composio.dev
|
|||
|---------|-------------|
|
||||
| `onboard` | Quick setup (default) |
|
||||
| `onboard --interactive` | Full interactive 7-step wizard |
|
||||
| `onboard --channels-only` | Reconfigure channels/allowlists only (fast repair flow) |
|
||||
| `agent -m "..."` | Single message mode |
|
||||
| `agent` | Interactive chat mode |
|
||||
| `gateway` | Start webhook server (default: `127.0.0.1:8080`) |
|
||||
| `gateway --port 0` | Random port mode |
|
||||
| `daemon` | Start long-running autonomous runtime |
|
||||
| `service install/start/stop/status/uninstall` | Manage user-level background service |
|
||||
| `doctor` | Diagnose daemon/scheduler/channel freshness |
|
||||
| `status` | Show full system status |
|
||||
| `channel doctor` | Run health checks for configured channels |
|
||||
| `integrations info <name>` | Show setup/status details for one integration |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue