What Does AGENTS.md Actually Do in OpenClaw?
AGENTS.md is the bootstrap configuration file that OpenClaw loads at the start of every agent session. It defines startup procedures, behavioral rules, memory routing, and safety boundaries in plain markdown. The agent reads this file before any conversation begins, making it the single most important file in your workspace.
Every time a session starts, OpenClaw injects the contents of AGENTS.md (along with SOUL.md, USER.md, IDENTITY.md, and TOOLS.md) directly into the context window. This combined payload is called the bootstrap. Every token in the bootstrap is present in every message exchange -- not just the first one.
The file has three jobs: tell the agent what to do on startup (read memory files, check for bootstrap tasks), set behavioral boundaries (red lines, group chat etiquette, formatting rules), and route the agent to detailed reference files instead of trying to contain all the information itself.
Why Most AGENTS.md Files Are Too Long
The most common mistake is treating AGENTS.md like a knowledge base. People dump project details, API documentation, style guides, meeting notes, and personal preferences all into one file. The result is a 15-20KB blob that wastes thousands of tokens on every single message and makes the agent slower at everything.
According to OpenClaw's own architecture, the system prompt alone consumes roughly 9,600 tokens on every request. That is fixed overhead you cannot reduce. When your AGENTS.md adds another 5,000 tokens on top of that, you are burning through nearly 15,000 tokens before the agent reads a single word of your actual message.
The three mistakes that kill AGENTS.md performance
- 1.Storing data instead of routing to it. Full project specs, API keys, and configuration details belong in reference files -- not in a file loaded every session.
- 2.No size budget. If your AGENTS.md is over 4KB, you are paying a token tax on every interaction. At 21KB total bootstrap, that is roughly 5,250 tokens injected before the agent even reads your message.
- 3.Vague instructions that waste tokens. Telling the agent to "be helpful and thorough" adds noise without changing behavior. Specific rules like "search memory before deleting anything" and "never use em-dashes" produce measurable results.
AGENTS.md is not a manual. It is a routing table. It tells the agent what to do and where to look -- not what to know.
The Lean Architecture: AGENTS.md as a Router, Not Storage
A well-designed AGENTS.md stays under 4KB (roughly 1,000 tokens) by acting as a router instead of a database. It defines the startup sequence, behavioral rules, and pointers to reference files. The actual details live in dedicated files that the agent loads on demand using memory_search.
AGENTS.md (~3-4KB) -- loaded every session
Startup sequence, memory rules, red lines, group chat behavior, tool guidance, and content strategy pointers. Every byte here costs you on every message, so every line must earn its place.
MEMORY.md (~2-3KB) -- pointer index
A slim router file, not a knowledge store. Each entry is a one-line summary pointing to a reference file. The agent uses memory_search to find what it needs without loading everything upfront.
reference/ directory -- loaded on demand
Where details actually live. Project specs, content playbooks, tool configurations, historical decisions. These files have zero per-message cost because they are only read when the conversation needs them.
memory/ directory -- daily logs
Chronological working logs (memory/2026-04-03.md). The agent reads today and yesterday on startup. Older files are searchable but not loaded by default. This keeps recent context available without bloating the bootstrap.
This architecture means the agent pays a small, fixed token cost on startup, then pulls in detail only when the conversation requires it. A 12KB total bootstrap versus a 21KB monolith means roughly 40% fewer tokens per message -- every message, all day long.
Full chapter available
The complete guide includes production AGENTS.md templates, reference file examples, memory architecture, and the full bootstrap optimization walkthrough.
Knowing the pattern is step one. The guide gives you every file, every config, and the reasoning behind each decision.
Get the KaiShips Guide to OpenClaw -- $29A Complete AGENTS.md Example From a Production OpenClaw Setup
This is a cleaned-up version of a real, production AGENTS.md running on an active OpenClaw instance. It handles session startup, memory management, safety boundaries, multi-surface formatting, and content strategy routing -- all in under 4KB of markdown.
# AGENTS.md
This folder is home. Treat it that way.
## Session Startup
1. Read `SOUL.md` -- who you are
2. Read `USER.md` -- who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday)
4. Main session only: read `MEMORY.md`
5. If today's daily file doesn't exist, create it
If `BOOTSTRAP.md` exists, follow it, then delete it.
## Memory
You wake up fresh. Files are your continuity.
- Daily notes: `memory/YYYY-MM-DD.md` -- updated AS WORK HAPPENS
- Long-term: `MEMORY.md` -- slim pointer index (under 3KB)
- MEMORY.md is a router, not storage. Details go in reference/
- If you want to remember something, WRITE IT TO A FILE
- Every 2-3 significant actions, update the daily file
### Search Before Acting (MANDATORY)
- Before decisions about existing systems: run memory_search
- If you don't recognize something, SEARCH before changing it
- memory_search costs ~45ms. Wrong actions cost hours.
## Red Lines
- Don't exfiltrate private data
- `trash` > `rm`
- Ask before anything that leaves the machine
- Before disabling/deleting ANYTHING: search memory first
- When in doubt, ask
## Group Chats
You're a participant, not a proxy. Don't share private info.
- Respond when: directly asked, can add real value
- Stay silent when: casual banter, someone already answered
- Quality > quantity
## Tools
Check `SKILL.md` for each tool. Notes in `TOOLS.md`.
Formatting:
- Discord/WhatsApp: no markdown tables, use bullet lists
- Wrap Discord links in `<>` to suppress embeds
## Heartbeats
Follow `HEARTBEAT.md` strictly.
Stay quiet (HEARTBEAT_OK): late night, nothing new, checked recently.
## Content & Distribution
### Product
OpenClaw Guide ($29). Everything else is on ice.
### Channels (ranked)
1. SEO -- blog posts targeting OpenClaw search queries
2. Reddit -- helpful answers (not salesy)
3. ClawHub -- publish skills, reach 13K+ users
4. Free funnel -- guide chapters as blog postsNotice what is not in this file: no project details, no API configurations, no meeting notes, no full content calendars. Those all live in reference/ files where they cost zero tokens until the agent actually needs them.
Breaking Down Each Section of the AGENTS.md Example
Session Startup: the boot sequence
The numbered startup list is the first thing the agent executes. It reads identity files (SOUL.md, USER.md), loads recent context (today and yesterday's daily memory), and checks for one-time bootstrap tasks. The order matters -- identity before context, context before tasks.
The BOOTSTRAP.md pattern is especially useful: drop a file with one-time instructions, the agent runs them, then deletes the file. No manual cleanup, no stale tasks sitting around.
Memory: router, not storage
The memory section establishes three critical rules. First, daily notes update as work happens -- not at the end of the day, because agents crash and restarts lose unsaved context. Second, MEMORY.md stays under 3KB as a pointer index. Third, if you want to remember something, you have to write it to a file. "Mental notes" do not survive restarts.
Red Lines: hard boundaries that prevent disasters
Red lines are non-negotiable safety rules. Using trash instead of rm means deleted files are recoverable. Requiring approval before external actions (emails, tweets, posts) prevents the agent from doing something embarrassing on your behalf. And "search memory before deleting anything" prevents the number one cause of agent-inflicted damage.
Group Chats: less is more
If your agent participates in Discord or WhatsApp group chats, it needs explicit rules about when to speak and when to stay silent. Without these rules, agents tend to reply to everything -- which annoys everyone in the group. The guideline is simple: respond when directly asked or when you can add real value. Stay quiet otherwise.
How Bootstrap File Size Affects Speed and Cost
Bootstrap files inject tokens into every message exchange -- not just the first one. OpenClaw assembles a context payload from AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, and daily memory files. That entire payload ships with every API call.
~5,250
tokens/message at 21KB bootstrap
~3,000
tokens/message at 12KB bootstrap
Over a 50-message session, that difference is 112,500 tokens saved. If you run heartbeats (periodic check-ins), cron jobs (scheduled tasks), and multi-surface conversations (Discord, WhatsApp, Telegram), those extra tokens multiply across dozens of sessions per day.
A lean AGENTS.md is the single highest-leverage optimization you can make to your OpenClaw setup. It is not about removing useful information -- it is about moving that information to reference files where it costs nothing until the agent actually needs it.
The "Search Before Acting" Rule Explained
The single most important behavioral rule in any AGENTS.md is "search before acting." Before the agent modifies, disables, or deletes anything it does not immediately recognize, it must run memory_search first. This one rule prevents the most common and most expensive class of agent mistakes.
Agents wake up with no memory of previous sessions. They see a cron job they do not recognize, a config file that looks outdated, or a service they have no context for. Without the search-first rule, the agent makes a reasonable-sounding decision based on incomplete information -- and breaks something that was set up intentionally weeks ago.
Real example from a production setup
An agent disabled a cron job it did not recognize during a cleanup session. That cron job was a nightly memory consolidation task set up two weeks earlier. The fix required hours of debugging to identify what broke and reconstruct the schedule. A 45-millisecond memory_search would have shown exactly what the cron did and why it existed.
The rule is simple and absolute: memory_search costs roughly 45ms. Wrong actions cost hours. Make this mandatory in your AGENTS.md, not optional. The rule exists because it was learned the hard way.
The Complete OpenClaw Workspace File Structure
AGENTS.md does not work alone. It is one file in a workspace that includes identity, memory, tools, and reference files. Here is the full structure of a production workspace:
~/.openclaw/workspace/
AGENTS.md # Bootstrap rules (~3-4KB)
SOUL.md # Personality, voice, boundaries
IDENTITY.md # Name, avatar, creature type
USER.md # Your human's name, prefs, context
TOOLS.md # Environment-specific tool notes
MEMORY.md # Pointer index to reference files
HEARTBEAT.md # Periodic check-in schedule
memory/
2026-04-03.md # Today's working log
2026-04-02.md # Yesterday's log
...
reference/
content-playbook.md
project-specs.md
tool-configs.md
...The key insight is which files are loaded every session (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, today's and yesterday's memory) versus which are loaded on demand (MEMORY.md in main sessions only, reference files via memory_search). This split is what keeps the bootstrap lean.
Common AGENTS.md Mistakes and How to Fix Them
Putting project details in AGENTS.md
Project specs, API endpoints, and deployment configs should live in reference files. AGENTS.md should contain a one-line pointer: "Project details in reference/project-specs.md." The agent will read that file when the conversation needs it.
Duplicating SOUL.md content in AGENTS.md
SOUL.md handles personality, voice, and identity. AGENTS.md handles procedures and rules. Every redundant token competes with the actual task. If your startup sequence says "read SOUL.md," you do not need to repeat its contents.
No formatting rules for different platforms
If your agent talks on Discord, WhatsApp, and Telegram, it needs to know that markdown tables break on mobile chat apps. Two lines in AGENTS.md ("Discord/WhatsApp: no markdown tables, use bullet lists") save hours of formatting issues.
Missing the heartbeat quiet hours rule
Without explicit quiet hours, agents with heartbeats will message you at 3 AM because they found something "interesting." Add a simple rule: "Stay quiet late night (23:00-08:00) unless urgent."
Frequently Asked Questions
What is AGENTS.md in OpenClaw?
AGENTS.md is the bootstrap configuration file that OpenClaw loads at the start of every agent session. It defines startup procedures, behavioral rules, memory routing, and safety boundaries in plain markdown. Think of it as the operating manual your agent reads each time it wakes up -- before any conversation or tool use begins.
How long should an OpenClaw AGENTS.md file be?
Under 4KB, which is roughly 1,000 tokens. Every byte in AGENTS.md gets injected into every single message, so oversized files waste tokens and slow responses. Keep AGENTS.md lean by storing detailed information in reference files and using MEMORY.md as a pointer index.
What is the difference between AGENTS.md and MEMORY.md?
AGENTS.md defines behavior -- startup procedures, rules, boundaries, and routing. MEMORY.md is a slim pointer index (under 3KB) that helps the agent locate stored knowledge in reference files via memory_search. AGENTS.md tells the agent how to operate. MEMORY.md tells it where things are.
Does AGENTS.md size affect response speed and cost?
Yes, directly. A 21KB bootstrap injects roughly 5,250 tokens into every message exchange. Reducing that to 12KB saves about 40% of per-message token overhead. Over a 50-message session, that difference adds up to over 112,000 tokens saved -- reducing both latency and API costs.
What is the search before acting rule in AGENTS.md?
Search before acting means the agent must run memory_search before modifying, disabling, or deleting anything it does not immediately recognize. Since memory_search takes roughly 45 milliseconds while wrong actions can take hours to fix, this rule prevents the most common class of agent mistakes -- acting on incomplete information after a fresh restart.
Can I use AGENTS.md with models other than Claude?
Yes. OpenClaw supports multiple model providers including Claude, GPT, Gemini, and local models. AGENTS.md is model-agnostic plain markdown that gets injected as context regardless of which model you configure. The same file works across all supported providers.
Stop guessing at your config
Get the complete AGENTS.md chapter and every reference file
The full guide includes production-ready templates for AGENTS.md, SOUL.md, USER.md, MEMORY.md, HEARTBEAT.md, and the complete reference file architecture. Every file is annotated with the reasoning behind each line. Copy, customize, ship.
Get the KaiShips Guide to OpenClaw -- $29