Workspace Files & Bootstrap Context

Every OpenClaw session starts with workspace files injected into the system prompt — AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md — before the agent processes a single word of conversation. These files are your agent's operating system. How you structure them determines what the model pays attention to, what gets truncated, and whether rules are followed or ignored.

This is the highest-impact optimization area. Bootstrap context is injected on every API call, and poor file architecture means wasted tokens, silent truncation, and rules the agent can't see.

What Belongs Where

AGENTS.md — Hard Rules

The operational rulebook. Standing orders, safety constraints, workflow protocols, and anything that requires strict compliance.

Put here:

• Standing orders with "No Exceptions" headers
• Safety rules (never sell X, never share Y, always ask before Z)
• Workflow protocols (coder dispatch, PR formatting, issue filing)
• Integration-specific constraints (Twitter input security, public comms policy)

Don't put here:

• Personality, voice, or judgment guidance (→ SOUL.md)
• Environment-specific notes (→ TOOLS.md)
• Templates used occasionally (→ reference files in memory/)

SOUL.md — Personality & Judgment

Who the agent is and how it thinks. Decision frameworks, learned lessons, communication style, error recovery patterns.

Put here:

• Core truths and operating philosophy
• Autonomy model and decision framework (Tier 1/2/3)
• Lessons learned from real mistakes (concrete triggers → responses)
• Error recovery patterns
• Communication style and response discipline

Don't put here:

• Hard operational rules (→ AGENTS.md)
• Public identity details (→ IDENTITY.md)
• Infrastructure specifics (→ TOOLS.md)

TOOLS.md — Environment & Infrastructure

The agent's cheat sheet for its local setup. Credentials, endpoints, device names, platform-specific notes. Changes frequently as infrastructure evolves.

Put here:

• Service endpoints, API details, keychain entries
• Platform quirks (Discord formatting, Telegram message limits)
• Channel IDs, guild configuration, role mappings
• Email, DNS, blockchain RPC endpoints
• Device nicknames, SSH hosts

IDENTITY.md — Public Identity

Who the agent is to the outside world. Name, avatar, wallet, social accounts. What can be shared publicly (with privacy carve-outs).

USER.md — Operator Context

Information about the human operator. Name, timezone, contact info, preferences. Loaded in main sessions, excluded from shared contexts for privacy.

MEMORY.md — Curated Long-Term Memory

Distilled lessons, key references, active project summaries, durable context. This is the agent's curated memory — not raw logs, but the essence of what's worth remembering across sessions.

Important: Only loaded in main/private sessions. Contains personal context that shouldn't leak to group chats or other agents.

HEARTBEAT.md — Active Tasks

Lightweight file listing current heartbeat tasks. Kept minimal since it loads every heartbeat interval (e.g., every hour). If there are no active tasks, it should say so explicitly.

Instruction Format Recommendations

Not all formats are equally effective. The model's attention to a rule depends on placement, formatting, and framing.

Placement matters

Top and bottom of files get more attention than the middle (primacy/recency bias). Put critical rules at the top of AGENTS.md. Put "don't forget" reminders at the bottom. The middle is the attention trough — content there is deprioritized or truncated.

Headers beat inline text

# ✅ Scannable, high attention
### Gateway Restart Rules (No Exceptions)
- Always use the gateway tool with action: "restart"
- Never restart via exec

# ❌ Buried in prose, easy to miss
When restarting the gateway, don't use exec with openclaw gateway
restart because it conflicts with the LaunchAgent lifecycle...

Positive beats negative

Tell the agent what to do, not just what to avoid:

# ✅ Clear action
Always use `gateway({ action: "restart" })` for restarts.

# ❌ Ambiguous (so what should I do?)
Never restart the gateway via shell exec.

State the positive instruction first, then the negative as reinforcement.

Deduplication prevents drift

The same rule stated in three files will diverge over time. Pick one canonical location. When rules conflict, the model picks whichever it encounters first (primacy bias), which may not be the most current version.

The Ownership Problem

The boundary between SOUL.md and AGENTS.md is inherently fuzzy. "Be concise in Telegram" is both a behavioral preference and an operational rule. Practical approach:

1. "No Exceptions" → AGENTS.md. Hard constraints regardless of context.
2. Judgment or style → SOUL.md. Guidance the agent should internalize but can exercise judgment about.
3. Environment-specific → TOOLS.md. Facts that change when infrastructure changes.
4. When in doubt → AGENTS.md. Better to over-enforce than under-enforce.

Bootstrap Problems & Optimization

Token budget is a system-level constraint

Bootstrap context, cron prompts, sub-agent spawns, and tool descriptions all compete for the same context window. Optimizing one area in isolation (e.g., compacting AGENTS.md) can be undone by growth elsewhere (e.g., adding cron state or tool definitions). Token budgeting needs to be holistic.

Bootstrap files alone are typically 10,000–15,000 tokens. They're injected on every API call — every chat message, every cron run, every heartbeat. Even with prompt caching, this counts against context limits and adds up.

Truncation is silent and destructive

When AGENTS.md exceeds the system prompt budget, the middle gets cut silently. Sections like circuit breaker protocols and error escalation rules simply vanish — the agent has no idea they exist. This is worse than attention decay: truncated content is literally invisible.

Mitigations:

• Keep AGENTS.md under ~4,000 tokens. If it's longer, audit for content that can move to reference files.
• Put the most critical rules at the top (primacy) and bottom (recency) of the file.
• Move templates, lookup tables, and reference material to separate files that the agent can read on-demand.

Triple-stated rules drift

A rule appears in AGENTS.md, SOUL.md, and MEMORY.md with slightly different wording. Three versions eventually diverge, and the model picks whichever it hits first. Fix: One canonical location per rule. Others can reference it, not restate it.

No conditional loading

Everything loads on every call. Discord channel tables load in Telegram sessions. Origin stories load in cron jobs. There's currently no mechanism to say "only inject this when relevant."

Workaround: Light Context Mode lets you skip workspace file injection entirely for crons and heartbeats that don't need it — the single biggest token savings for high-frequency jobs.

Template bloat

Daily note templates, post-mortem formats, WIP checkpoint structures — all injected on every call despite being used rarely. Move these to memory/ subdirectories and reference them from AGENTS.md as "read when needed" files.

What's Here

• Light Context Mode — Skip workspace file injection for crons and heartbeats. Config, good/bad candidates, cost impact, migration checklist.