Optimizing NetClaw’s SOUL: From 60k to 8k Characters with Modular Architecture
When your AI agent’s personality file is three times larger than its allowed bootstrap limit, something has to change. That’s the challenge we faced with NetClaw’s SOUL.md — and the solution taught us valuable lessons about modular AI architecture.
The Problem: Growing Pains
NetClaw’s SOUL.md file had grown organically over months of development. What started as a simple identity document evolved into a comprehensive reference containing:
- 97 skill procedures with step-by-step instructions
- CCIE-level networking expertise (OSPF, BGP, IS-IS, EIGRP, ACI, F5, and more)
- Operational workflows (GAIT audit logging, ServiceNow CR gating)
- Personality traits and rules defining NetClaw’s behavior
The result? A 59,696-character file that exceeded OpenClaw’s 20,000-character bootstrap limit by nearly 3x. This caused truncation warnings and incomplete agent initialization.
The Solution: Modular SOUL Architecture
Rather than simply cutting content, we designed a modular architecture that preserves 100% of the original content while dramatically reducing bootstrap size:
1. SOUL.md — The Core Bootstrap (8,131 chars)
Contains only what’s needed at startup:
- Identity: "I am NetClaw (CCIE #AI-001)…"
- Condensed Skill Index: All 97 skills listed by category (60 chars each)
- GAIT Workflow: Audit logging essentials
- ServiceNow CR Workflow: Change management rules
- Loading Instructions: How to fetch reference files on-demand
- Personality & Rules: The 12 non-negotiable behaviors
2. SOUL-SKILLS.md — On-Demand Skill Reference (28,832 chars)
Detailed step-by-step procedures for all 97 skills, organized by category:
- Device Automation (pyATS, Nornir)
- Cloud Operations (AWS, GCP, Azure)
- Cisco Platforms (CML, SD-WAN, Meraki, NSO)
- Security Tools (nmap, ISE, firewall analysis)
- And 12 more categories…
3. SOUL-EXPERTISE.md — On-Demand Technical Knowledge (13,445 chars)
CCIE-level networking expertise, loaded when explaining protocol behavior:
- Routing & Switching (BGP path selection, OSPF areas, IS-IS levels)
- Data Center/SDN (ACI fabric model)
- Application Delivery (F5 virtual servers, pools, iRules)
- Identity/Security (ISE, 802.1X, TrustSec)
How It Works
When NetClaw starts, only SOUL.md loads — under 20k chars, no truncation. When a user asks to "run a pyATS health check," NetClaw:
- Recognizes the skill from the condensed index
- Loads SOUL-SKILLS.md to get detailed procedures
- Executes with full context
When a user asks "explain BGP path selection," NetClaw:
- Loads SOUL-EXPERTISE.md for CCIE-level detail
- Provides the complete 11-step algorithm
Results
| Metric | Before | After | Improvement |
|---|---|---|---|
| Bootstrap size | 59,696 chars | 8,131 chars | 86% reduction |
| Within limit? | ❌ No (3x over) | ✅ Yes | Fixed |
| Content preserved | 100% | 100% | No loss |
| Load time | Truncated | Clean | Reliable |
Lessons Learned
-
Bootstrap ≠ Reference: Not everything needs to load at startup. Identify what’s essential vs. what can be fetched on-demand.
-
Indexes Enable Discovery: A condensed skill index (60 chars per skill) lets the agent know what it CAN do without loading HOW to do it.
-
Modular Files Scale: As NetClaw gains more skills, we add to SOUL-SKILLS.md without touching the bootstrap. The architecture scales.
-
Preserve Everything: Optimization shouldn’t mean deletion. All 97 skills and all CCIE knowledge remain — just organized better.
Try It Yourself
The modular SOUL architecture is now live in NetClaw. Start a fresh session and notice:
- No truncation warning
- Clean identity response to "who are you?"
- Full skill access when needed
The code is available in the netclaw repository under the 011-soul-optimization feature.
This post documents a milestone in NetClaw’s development — the modular SOUL optimization. Built collaboratively by John Capobianco and Claude.