The OpenClaw Context Budget Playbook

Picture the rule that matters most on your host sitting at the bottom of a long file. It says never to send anything outside the building without a human approval, and for months the agents follow it. Then the text above it grows, mostly memory notes the agent adds to itself overnight, until the session cuts the bootstrap off a few lines short. Nobody deleted the rule. The agent just stopped seeing it, and nothing anywhere turned red.

That is one of the four silent failures in the observability guide: a bootstrap that overflowed the context budget, so the agent lost part of its instructions and executed the part it still had. This page is about keeping that from happening on one always-on machine running the OpenClaw gateway.

What the Ranking Guides Already Cover

The articles that rank for agent context management run long, between roughly 3,500 and 8,000 words, and they agree on the basics. Persistent instructions cost you tokens in every session, so keep them short. Give each file one job. Prune memory on a schedule. One of them suggests running wc -m on the workspace and dividing by four for a rough token count, which is a fine habit.

All of that is right. It also stops at the writing stage, treating file size as something you fix once with discipline. On a host where an agent writes to its own memory every night, size is a number that moves, and a number that moves needs a check that runs without you.

Know Which Files Ride in Every Session

On a typical setup the workspace holds SOUL.md for personality and values, AGENTS.md for operating rules, IDENTITY.md for name and role, TOOLS.md for tool notes, and MEMORY.md, the curated long-term memory that gets injected into every main-agent session. The first agent setup guide walks through creating them. Each one is cheap on day one.

They don't grow at the same rate, and that is the useful part. SOUL.md and IDENTITY.md barely change after the first week. AGENTS.md grows in bursts, usually right after an incident, when someone adds a rule so the bad thing never happens again. MEMORY.md grows every single night, because the nightly review that decides what to keep almost always decides to keep something.

So the file most likely to push you over is the one written by the agent itself.

Measure Every Night, Alert on the Trend

Write a plain script that records the size of each bootstrap file once a day, appends one line of JSON to a log, and compares today against a budget you set. Run it from launchd or cron, outside the gateway, for the same reason the observability guide gives for heartbeat watchers: if the detector is an agent, it can narrate its own success.

#!/bin/zsh
WS=~/.openclaw/workspace
LOG=~/state/context-budget.jsonl
BUDGET=48000   # chars across all bootstrap files; set from your own measurement
total=0
for f in SOUL.md AGENTS.md IDENTITY.md TOOLS.md MEMORY.md; do
  n=$(wc -m < "$WS/$f" 2>/dev/null || echo 0)
  total=$((total + n))
  echo "{\"ts\":\"$(date -u +%FT%TZ)\",\"file\":\"$f\",\"chars\":$n}" >> "$LOG"
done
pct=$((total * 100 / BUDGET))
[ "$pct" -ge 80 ] && notify "bootstrap at ${pct}% of budget ($total chars)"

The 48,000 in that script is a placeholder, and I mean that. Your real limit depends on your OpenClaw version and how you have it configured, so find the number that applies to your install, then set the budget a comfortable distance under it. Alert at 80 percent, because by the time you hit 100 the agent has already been running on partial instructions.

The trend line is worth more than the threshold. If MEMORY.md gained 300 characters a night for three weeks, you can see the day it crosses, and you get to fix it on a weekday afternoon instead of discovering it from a strange decision at 2 in the morning.

Plant a Canary at the Bottom of Each File

Measuring characters tells you how close you are. It doesn't tell you what the agent actually saw, and those two can disagree, because a new file, a renamed file or a config change can shift what gets injected without any file growing at all.

So I put a canary on the last line of every bootstrap file. A short, meaningless token, different per file, something like canary-agents: tern-41. Then a scheduled job, triggered with openclaw cron run while you test it, starts a fresh session and asks the agent to repeat the canary from each file without opening any files. A complete answer means every tail made it in. A missing canary means that file got cut, and the job writes a failure line instead of a heartbeat.

Even where a runtime does tell the agent that something was truncated, that note goes to the agent, and the agent is the one party you can't rely on to report it. The canary goes to you.

Rotate the canary values when you rotate anything else, so the agent can't answer from an old memory note that happens to quote last month's token. And keep the check honest by asking only for the canaries. If the prompt explains why you are asking, a clever model will sometimes guess.

Give MEMORY.md a Hard Cap and a One-In, One-Out Rule

Memory needs a fixed line budget, enforced by the job that writes it, and the agent should have to remove something every time it adds something once the cap is reached. I would hold this line harder than anything else here. A memory file that only grows turns into an archive, and an archive is the wrong thing to inject into every session.

The nightly review is where to enforce it. Have it write the new MEMORY.md to a temp file, count lines, and refuse to mv it into place if it is over the cap. A refused write leaves yesterday's memory intact and logs one line saying the review needs a human. Older entries that still matter go into dated files under memory/, where the agent can read them on demand without paying for them in every session. The idempotent jobs playbook covers the temp-file-and-move pattern if you haven't built it yet.

Move the Rules That Must Never Be Cut

Put the non-negotiable rules at the top of AGENTS.md, not the bottom.

Better still, move them out of prose entirely. An approval rule like the one in the opening belongs in a queue the agent cannot empty, with an executor that holds the only credential, as described in the human approval gates playbook. Once a rule lives in machinery, losing the sentence about it costs a little clarity and nothing else. Incident-driven rules are the best candidates, because they are the ones that pile up in AGENTS.md after a bad week and then sit there forever. When you add one, ask whether a script could enforce it, and if so, write the script and keep only a one-line pointer in the file.

Generated text helps too. If any bootstrap file describes the state of the system, such as which agents exist or which models they run, generate it from the source of truth, the way the configuration drift playbook recommends. A generated file has a predictable size, and a hand-edited one grows whenever somebody is in a hurry.

Rehearse the Overflow

Copy your workspace to a test agent, paste filler into MEMORY.md until the measurement script fires, and run the canary job. You want two things to happen: the 80 percent alert arrives before the canary check fails, and when the canary does fail, it names the right file. If the canaries all come back while you know the files are too large, your idea of the limit is wrong, and it is far better to learn that from a test agent with filler in its memory than from a real one with a rule it can no longer see.

Related Reading

• OpenClaw Agent Observability: Detecting Silent Failures
• The OpenClaw Human Approval Gates Playbook
• The OpenClaw Configuration Drift Playbook
• The OpenClaw Idempotent Jobs Playbook

Frequently Asked Questions

What is the context budget for OpenClaw bootstrap files?

It is the amount of workspace text, from files like AGENTS.md and MEMORY.md, that gets injected into each session before the agent starts work. The exact limit depends on your version and configuration, so measure your own install and set an alert well under it.

How do I know if my agent's instructions were truncated?

Put a unique canary token on the last line of each bootstrap file and have a scheduled job ask a fresh session to repeat them without opening any files. A missing canary means that file was cut before the end.

Why does MEMORY.md cause most overflows?

It is the only bootstrap file the agent writes to on a schedule, and nightly reviews tend to add more than they remove. A hard line cap, enforced by the job that writes the file, stops the growth.

Where should important rules go if bootstrap space is tight?

Put them at the top of AGENTS.md, and move the ones that matter most into machinery, such as an approval queue or a script check, so they hold even if the prose about them is lost.