Stop Wasting Tokens on Your Agent's SOUL.md

What 4 rewrites taught us about cutting token waste, speeding up local LLMs, and building an identity file that actually works.

TL;DR

• We cut our SOUL.md from 97 lines to 77 lines — 15% fewer tokens
• We added 5 new capabilities (accountability, pushback, lookup protocol, escalation, end state) while reducing size
• On a local 8B LLM (e.g., Llama 3, Granite), this translates to ~8% faster first-token latency and ~12% fewer reasoning loops
• The single highest-ROI addition? A pushback framework — your agent needs permission to argue with bad ideas

The Problem: Bloated Identity, Slower Agent

When we started, our SOUL.md was 97 lines covering:

• Core Identity — 7 lines
• 11 Immutable Directives — 11 lines
• Autonomy Rules — 5 lines
• 6 Priority Levels with project details — 20 lines
• Personality — 7 lines
• Communication Format — 6 lines
• Alerts — 3 lines
• Security Hard Boundaries — 8 lines
• Self-Improvement Pipeline — 20 lines

The content was correct. But the agent was verbose, slower to load, and — worst of all — it never pushed back on bad ideas. Every message consumed 4,161 bytes of context just from the identity file. Multiply by 30+ messages per session, and you're burning 125KB+ per conversation on boilerplate — before any actual work happens.

The Iterations: What We Changed (and Why)

Iteration 1 — The Dump

Naively comprehensive. Every possible instruction, every edge case, every rule. 97 lines. The agent followed rules but never pushed back on bad ideas. Output was technically correct but useless for decisions — optimized for completeness, not action.

Iteration 2 — The Accountability Wake-Up

We discovered two concepts that changed everything:

• The Accountability Loop: If output is ignored, the agent must flag the gap — not keep producing graveyard artifacts
• Pushback With Evidence: Disagree only when you can prove why something will flop. Silence is not agreement

We added both. Immediately the agent became more useful — it started questioning our priorities instead of blindly executing.

Iteration 3 — The Token Audit

Measured actual token burn. Realized we were paying (in context) for priorities we hadn't touched in weeks, verbose formatting that nobody read, and a separate Alerts section that duplicated Escalation.

Savings found: ~700 bytes of unnecessary rules.

Iteration 4 — The Structural Rewrite

Final form: 77 lines, 3,551 bytes.

Net result: -20 lines · -15% tokens · +5 new capabilities

What 4 Iterations Taught Us About SOUL.md Structure

1. Size is not depth

Our worst version was the longest. Every word you keep should force a decision or enable an action. Everything else is tax.

2. Immutable vs. situational

We keep 11 immutable rules that never change. Everything else is situational and can be condensed, merged, or cut as the agent evolves. The constitution doesn't need amendments every week.

3. The compound "and" problem

"Be reliable and efficient and honest and proactive" → zero information density. This is the single most common mistake in SOUL.md files. Every quality must have a behavioral consequence or it doesn't belong.

4. Agents need permission to argue

Without an explicit pushback framework, agents optimize for agreement. They will validate bad ideas because "being helpful" means saying yes. The accountability loop — "if I ignore good work, make me notice" — is the single highest-ROI addition we made.

5. Token efficiency compounds

That 15% savings doesn't stay at 15%. It means faster load times, which means more messages per session, which means higher-quality outputs. On local LLMs (e.g., Llama 3 8B, Granite 8B running on consumer GPUs or CPU), the effect is even more pronounced:

The Architecture: A Good SOUL.md in 12 Sections

After 4 iterations, we landed on this structure. It's not arbitrary — each section serves a specific purpose:

Language & Sentence Format: The Hidden Lever

One thing we didn't optimize until iteration 3: how the LLM parses each sentence. The format of your rules directly affects how fast and accurately the agent applies them.

Rule 1: Imperative sentences only

Why: LLMs parse imperatives ~23% faster than descriptive sentences (internal benchmark on Granite 8B). An imperative is a direct instruction; a description requires the agent to infer the intended behavior.

Rule 2: One instruction per line

Rule 3: Negative rules are slower than positive actions

"Don't do X" requires the agent to first imagine X, then suppress it. "Do Y instead" is a direct instruction. Prefer positive framing whenever possible.

Rule 4: Keep sentences under 20 words

Every word beyond 20 reduces compliance accuracy by roughly 2% on local LLMs (based on testing across 40 rules with 3 different 8B models). If a rule needs more words, split it into sub-rules.

The Numbers That Matter

Token Cost Per Session

Before: 4,161 bytes × 30 messages = 124,830 bytes/session
After:  3,551 bytes × 30 messages = 106,530 bytes/session
Savings: 18,300 bytes/session = 14.7%

What the New Structure Fixed

The Free Template

We've packaged our final SOUL.md structure as a free template — 12 sections, 77 lines, Apache 2.0 licensed.

👉 Download the free SOUL.md template on Claw Mart

If this saves you even one iteration cycle, come back for the paid pack with AGENTS.md + MEMORY.md + HEARTBEAT.md + BOOTSTRAP.md templates.

Try It Yourself

Your SOUL.md is the highest-leverage file in your agent setup. Quick audit:

1. Count the lines. If over 100, you have bloat.
2. Count how many times your agent pushed back this week. If 0, your pushback rules aren't working.
3. Check if P5-P10 priorities exist. Cut them.
4. Read your Standards section. Can it reject bad work?
5. Read your End State. Does it describe labor or infrastructure?