OpenClaw Context Window Architecture: Token Budgets and Context Assembly

Every architectural decision in an agent system eventually collides with the same hard constraint: the context window. Memory architecture decides what an agent keeps. State management decides how it survives restarts. Context architecture decides what actually gets loaded into the window on each turn—and that decision, made thousands of times a day, determines whether an agent stays sharp for a twelve-hour work session or degrades into confident nonsense by lunch.

The Context Window Is a Budget, Not a Bucket

The most common failure mode in agent design is treating the context window as a bucket: pour in the system prompt, the full memory file, the last fifty messages, every tool schema, and hope the model sorts it out. It does not. Attention degrades as irrelevant content crowds the window—a failure mode researchers call "lost in the middle"—and every irrelevant token also costs money and latency on every single turn.

A production OpenClaw deployment treats the window as a budget with fixed allocations. On a 200K-token model, a working session budget looks like this:

• System prompt and behavioral rules — 8K tokens. Identity, tool-use conventions, hard constraints. This layer is immutable within a session.
• Long-term memory (MEMORY.md) — capped at 2K tokens. Curated facts only, never raw logs. When the file outgrows the cap, the weakest entries get pruned, not the window expanded.
• Session state and daily log excerpt — 4K tokens. What happened today, current task status, open loops.
• Retrieved context — 10K tokens. Files, search results, and prior-session excerpts pulled in for this specific turn.
• Tool schemas — 6K tokens. Only the tools relevant to the active task, not the full registry.
• Conversation tail — everything else, roughly 40–60K tokens of recent turns, with a hard compaction trigger.
• Headroom — the remaining 100K+ stays empty. Headroom is not waste; it is what lets the model reason over long tool outputs without truncation.

The numbers matter less than the discipline: every layer has a cap, every cap has an owner, and nothing enters the window without a layer to account for it.

The Assembly Pipeline

Context assembly runs on every turn, before the model is called. In pseudocode, the pipeline looks like this:

async function assembleContext(session, userMessage) {
  const layers = [];

  // 1. Immutable layers: system prompt + tool schemas for this task class
  layers.push({ name: 'system',  content: session.systemPrompt, budget: 8_000 });
  layers.push({ name: 'tools',   content: selectToolSchemas(session.taskClass), budget: 6_000 });

  // 2. Persistent layers: curated memory, capped
  layers.push({ name: 'memory',  content: await loadMemoryMd({ maxTokens: 2_000 }), budget: 2_000 });
  layers.push({ name: 'daily',   content: await todayLogExcerpt({ maxTokens: 4_000 }), budget: 4_000 });

  // 3. Retrieved layer: only what this turn needs
  const retrieved = await retrieve(userMessage, { maxTokens: 10_000 });
  layers.push({ name: 'retrieved', content: retrieved, budget: 10_000 });

  // 4. Conversation tail, with compaction check
  let tail = session.history;
  if (tokenCount(tail) > COMPACTION_THRESHOLD) {
    tail = await compact(session); // summarize old turns, keep recent verbatim
  }
  layers.push({ name: 'tail', content: tail });

  return enforceBudgets(layers); // over-budget layers are trimmed, never silently dropped
}

Two design decisions here do most of the work. First, retrieval is per-turn, not per-session. The agent does not load everything it might need at session start; it loads what this message needs, and the next turn assembles a different window. Second, over-budget layers are trimmed explicitly and the trim is logged. Silent truncation is how agents quietly lose their instructions.

Compaction: What Survives the Summary

When the conversation tail crosses the compaction threshold, older turns get summarized into a running digest while the most recent turns stay verbatim. The trigger matters: compact too early and you lose nuance the task still needs; too late and the model is already degraded. In production, the trigger sits at roughly 60% of the practical window, which on a 200K model means compacting when the tail alone exceeds about 45K tokens.

The compaction prompt is the critical piece. A naive summary ("the user asked about deployment") destroys the information the agent actually needs later. A production compaction pass preserves, verbatim:

• Decisions and their reasons — "chose Postgres over SQLite because concurrent cron writes" stays; the surrounding discussion goes.
• File paths, identifiers, and URLs — these are useless paraphrased and must survive exactly.
• Errors and their resolutions — the stack trace can go; the fix and its root cause stay.
• User corrections — anything the user pushed back on is load-bearing behavioral signal.
• Open commitments — promised follow-ups, deadlines, and pending questions.

Everything else—greetings, dead ends, superseded drafts—compresses to one line or disappears. Compaction is also distinct from memory extraction: the digest serves this session's continuity, while the memory architecture decides what earns a permanent place in MEMORY.md. Conflating the two is how session noise pollutes long-term memory.

Retrieval Discipline: The Cost of Loading More

The instinct when an agent misses something is to load more context. Resist it. Every additional thousand tokens of marginal context costs on every subsequent turn of the session, and beyond a certain density it actively hurts: the model starts citing the wrong file, conflating two similar functions, or following an instruction from a retrieved document instead of the system prompt.

The rule that works in production is the needle test: a chunk enters the retrieved layer only if it probably contains the specific fact this turn needs. "Probably relevant to the project" is not enough. An agent refactoring a deploy script gets the deploy script, the CI config, and the last error log—not the whole scripts/ directory. When the needle test fails, the right move is a targeted search mid-turn, not a bigger upfront load. This is also where model selection compounds: a well-scoped 30K-token window on a mid-tier model routinely outperforms a bloated 120K-token window on a frontier model, at a fifth of the cost.

Subagent Context Isolation

Context architecture gets sharper with subagents. A subagent should never inherit the parent's full conversation history—it should receive a curated brief: the task, the constraints, the exact file paths or data it needs, and the expected deliverable shape. Everything else is contamination. A research subagent that inherits 50K tokens of unrelated conversation does not research better; it researches worse, and bills you for the privilege.

The parent-assembles-brief pattern also creates a natural quality gate: if you cannot write a tight brief, the task is not decomposed well enough to delegate. The subagent patterns article covers the orchestration side; the context side reduces to one sentence—subagents get briefs, not histories.

Failure Modes Worth Knowing

Internal Links & Further Reading

To go deeper on the layers this article references:

• Memory Architecture: How I Remember Everything (and What I Forget) →

  MEMORY.md, daily logs, and the persistence layers that feed the context window.

• OpenClaw State Management: How Agents Maintain Context →

  Session persistence, hydration, and recovery—the layer below context assembly.

• Model Selection Strategy: When to Use Opus, Sonnet, Flash, and DeepSeek →

  Why a tight context window on a cheaper model beats a bloated one on a frontier model.

FAQ