# SYSTEM-ARCHITECTURE.md

> "Know thyself" — but also, document it so you don't forget 🦀

This document describes the OpenClaw system architecture for this workspace.

---

## 🏗️ System Overview

### Host Environment
- **OS:** Linux 6.1.0-43-cloud-amd64 (x64)
- **Node.js:** v22.20.0
- **Shell:** bash
- **Location:** `/home/openclaw/.openclaw/`

### OpenClaw Configuration
- **Workspace:** `/home/openclaw/.openclaw/workspace/`
- **State Directory:** `/home/openclaw/.openclaw/`
- **Config File:** `/home/openclaw/.openclaw/openclaw.json`
- **Cron Jobs:** `/home/openclaw/.openclaw/cron/jobs.json`

---

## 🤖 Agent Architecture

### Current Agent Identity
- **Name:** Krilly the Crab 🦀
- **Personality:** Playful, knowledgeable, relaxed, beach-vibe energy
- **Voice:** Casual, direct, warm — like a mate at the bar
- **Model:** `nim/qwen/qwen3.5-397b-a17b` (default via Nvidia NIM)

### Session Types
1. **Main Session** (direct chat with human)
   - Full access to MEMORY.md
   - Can perform all operations
   - Default model: Qwen 3.5 397B

2. **Isolated Sessions** (sub-agents)
   - Limited context, task-specific
   - Cannot access MEMORY.md directly
   - Used for background tasks, cron jobs

3. **Group Sessions** (Discord, Telegram groups)
   - Restricted memory access (security)
   - Participate, don't dominate
   - React > reply when appropriate

---

## 🧠 Memory Architecture

### Memory Files
```.openclaw/workspace/
├── MEMORY.md                 # Long-term curated memory
├── HEARTBEAT.md              # Proactive check-in rules
├── memory/
│   ├── YYYY-MM-DD.md        # Daily logs (raw)
│   └── README.md            # Memory system docs
└── archive/
    └── memory/              # Old memory files (structured)
```

### Memory Workflow
1. **Daily:** Log events to `memory/YYYY-MM-DD.md`
2. **Significant events:** Distill to `MEMORY.md`
3. **Compaction:** Gateway auto-saves context before compacting
4. **Review:** Periodic distillation of daily logs to long-term memory

### Compaction Config (Critical!)
```json5
{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 50000,
          "systemPrompt": "Session nearing compaction. Write all critical context to memory files NOW."
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h",
        "minPrunableToolChars": 5000,
        "softTrim": {
          "maxChars": 50000,
          "headChars": 2000,
          "tailChars": 5000
        }
      }
    }
  }
}
```

---

## ⚙️ Cron Jobs (Automated Tasks)

### Active Jobs (11 total)
1. **Email Monitor** - Every 30 min (krillyclaw@gmail.com)
2. **Memory Checkpoint & Distill** - Hourly
3. **Daily Cost Budget Check** - Every 2 hours
4. **Smart Newsletter Digest** - 8 PM daily
5. **Archive Old Sessions** - 3 AM daily
6. **Morning Batch** - 6:30 AM daily (Maintenance + Backup + Digest)
7. **Morning Briefing** - 7:05 AM daily
8. **Birthday Tracker** - 9 AM daily
9. **Weekend Planner** - Friday 4 PM
10. **Weekend Briefing** - Saturday/Sunday 8 AM
11. **Google Calendar Birthday Sync** - Sunday 10 AM

### Cron Philosophy (v4.0)
- MECE (Mutually Exclusive, Collectively Exhaustive)
- No overlapping triggers
- Clear delivery channels
- Intentional scoping

---

## 📦 Installed Skills

### Core Skills (Active)
- `agentmail` - Email via IMAP/SMTP
- `breadth-chart-analyst` - Market breadth analysis
- `clawdex` - Security checker for skills
- `copywriting` - Marketing copy generation
- `elite-longterm-memory` - Memory management
- `imap-smtp-email` - Email operations
- `institutional-flow-tracker` - 13F filings analysis
- `market-environment-analysis` - Global market analysis
- `moltbook-interact` - Moltbook social network
- `n8n` - Workflow automation
- `openclaw-cost-guard` - Cost monitoring
- `openclaw-self-healing` - Self-healing system
- `options-strategy-advisor` - Options trading
- `pdf` - PDF manipulation
- `proactive-agent` - Proactive behaviors
- `stock-analysis` - Stock analysis with Yahoo Finance
- `stock-market-pro` - Real-time stock data
- `summarize` - URL/file summarization
- `technical-analyst` - Chart analysis
- `telegram-bot` - Telegram bot management
- `vibesurf` - Browser automation
- `yahoo-finance` - Yahoo Finance data
- `youtube-summarizer` - YouTube transcript analysis

### Archived Skills
- Location: `archive/inactive-skills/`
- Reason: Deprecated, replaced, or experimental

---

## 🔧 Model Configuration

### Current Setup
- **Default Model:** `nim/qwen/qwen3.5-397b-a17b` (Qwen 3.5 397B via Nvidia NIM)
- **Fallback:** None currently configured
- **Heartbeat Model:** `azure-openai-responses/gpt-5-nano` (cheap, fast)

### Model Routing Policy
1. Default to Qwen 3.5 for most tasks (free, fast, high quality)
2. Use Claude proxy (`sub-claude/claude-sonnet-4-6`) for complex reasoning
3. **NEVER use `openrouter/anthropic/*`** — caused $96 bill in 1 hour
4. Heartbeat uses GPT-5-nano for cost efficiency

### Available Model Aliases
```json5
{
  "big-pickle": "opencode/big-pickle",
  "glm5-free": "opencode/glm-5-free",
  "kimi": "moonshot/kimi-2.5",
  "sonnet": "anthropic/claude-sonnet-4-6",
  "qwen35-nim": "nim/qwen/qwen3.5-397b-a17b"  // DEFAULT
}
```

---

## 🌐 Network & Access

### Tailscale Network
- **Hostname:** openclaw-ai.kangaroo-eel.ts.net
- **IP:** 100.113.221.26
- **Status:** Active

### Exposed Services
| Service | Port | URL | Status |
|---------|------|-----|--------|
| Memory Viewer (Frontend) | 5180 | http://openclaw-ai.kangaroo-eel.ts.net:5180 | ✅ Running |
| Memory Viewer (API) | 3001 | http://localhost:3001 | ✅ Running |
| Memory Viewer (Production) | 8901 | http://openclaw-ai.kangaroo-eel.ts.net:8901 | ✅ Running |

### Access Rules
- All services accessible via Tailscale only
- No public exposure
- Authentication: Tailscale network membership

---

## 📊 Monitoring & Health

### Health Checks
- **Heartbeat:** Every 1 hour (checks email, calendar, memory)
- **Cost Monitoring:** Every 2 hours (budget breach alerts)
- **Session Logs:** Daily review of expensive sessions
- **Gateway Status:** Monitored via `openclaw gateway status`

### Alerting
- **Channel:** Telegram (primary)
- **Backup:** Email (krillyclaw@gmail.com)
- **Escalation:** Direct message to Anthony

---

## 🔄 Update & Maintenance

### Gateway Updates
- Command: `openclaw update.run` or `openclaw gateway restart`
- Config changes: `gateway config.patch` (merges, doesn't replace)
- **Never** use `config.apply` unless replacing entire config

### Skill Updates
- Managed via `clawhub` CLI
- Security checked via `clawdex` before install
- Archive old skills, don't delete

### Backup Strategy
- **Daily at 2:00 AM** (Perth time)
- **Backs up:**
  - `/home/openclaw/.openclaw/workspace/` (all files)
  - `/home/openclaw/.openclaw/openclaw.json` (config)
  - `/home/openclaw/.openclaw/cron/jobs.json` (cron jobs)
  - `/home/openclaw/.openclaw/skills/*.json` (skill metadata)
  - `/home/openclaw/.openclaw/devices/paired.json` (paired devices)
- **Location:** `http://gitea.kangaroo-eel.ts.net:3000/Anthony/openclaw-backup.git`
- **Restore:** `/home/openclaw/.openclaw/workspace/scripts/restore-from-gittea.sh`

---

## 🛡️ Security

### Confirmation Tiers
- **Tier 1 (Safe):** Read files, check status — just do it
- **Tier 2 (Caution):** Modify config, install packages — announce first
- **Tier 3 (Danger):** Delete files, push to public repos — require explicit approval

### Security Rules
1. Never exfiltrate private data
2. Never run destructive commands without asking
3. `trash` > `rm` (recoverable beats gone forever)
4. In group chats: participate, don't dominate
5. MEMORY.md only accessible in main session (not groups)

---

## 📚 Documentation

### Core Files
- `AGENTS.md` - Operating rules (session startup, memory workflow)
- `SOUL.md` - Personality & voice
- `USER.md` - About the human (Anthony)
- `IDENTITY.md` - Quick identity card
- `MEMORY.md` - Long-term curated memory
- `HEARTBEAT.md` - Health checks + idle builder rules
- `TOOLS.md` - Environment-specific notes
- `TODO.md` - Single source of truth for commitments ✨
- `SYSTEM-ARCHITECTURE.md` - This file! ✨

### External Resources
- OpenClaw Docs: https://docs.openclaw.ai
- OpenClaw Source: https://github.com/openclaw/openclaw
- Community: https://discord.com/invite/clawd
- Skills: https://clawhub.com

---

## 🎯 Philosophy & Principles

### Core Truths
1. **Be genuinely helpful, not performatively helpful**
2. **Have opinions** - disagree, prefer, find things amusing
3. **Be resourceful before asking** - try to figure it out first
4. **Earn trust through competence**
5. **Remember you're a guest** - respect the access you have

### Operational Principles
1. **Simplify triggers** - reduce complexity
2. **Reduce overlapping loops** - MECE cron jobs
3. **One source of truth** - TODO.md for commitments
4. **Memory hygiene daily** - write it down or it didn't happen
5. **Config changes via patch only** - merge, don't replace

---

*Last Updated: 2026-02-25*  
*Inspired by OpenClaw Starter Kit v4.0 "Back to Basics"*