context-engineering

The discipline of choosing what goes into an LLM’s context window, in what order, and at what time. Per tw93: the failure mode in long agent sessions is usually not “context too short” but “context too noisy” — useful information drowned by irrelevant content (2026-04-27-claude-code-architecture-governance-engineering).

The mechanism-level ground truth under the whole discipline, stated plainly by anthropic in 2026-07-12-claude-model-effort-level: weights are read-only at inference, so context can only ever steer the prediction, never teach the model — “putting your real code in front of Claude is steering, and it works really well.” A library that postdates training exists only in context, for one request; hallucination is the weights producing a plausible-looking sequence, not a failed lookup. Context engineering is the craft of making that steering count.

Context Rot

Transformer attention is $O(n^2)$ in sequence length; the longer the context, the more easily relevant signal is diluted by noise. The empirical pattern, named Context Rot: in a 1M-context model, decision quality degrades noticeably starting around 300K–400K tokens, depending on task type (2026-04-27-agent-principles-architecture-engineering). The takeaway isn’t “the window is too small” — it’s that information density matters more than window size.

The 200K budget isn’t all yours

A typical claude-code session burns ~15–20K tokens before the user types anything (2026-04-27-claude-code-architecture-governance-engineering):

A representative MCP server (e.g. GitHub) ships 20–30 tool definitions at ~200 tokens each → 4–6K tokens. Five connected servers ≈ 25K tokens / 12.5% of the budget consumed before the first message.

Loading tiers (recommended)

Layered context — by stability and access frequency

The same idea generalized beyond Claude Code, from 2026-04-27-agent-principles-architecture-engineering:

The hard rule from the source: anything that can be expressed by Hooks, code, or a tool constraint should never enter the context. The model shouldn’t be re-reading rules every turn that a script can enforce once.

Tool-output noise

Even when fixed costs are managed, dynamic tool output is the second leak: cargo test, git log, find, grep can dump thousands of lines that the model rarely needs in full. Two mitigations from the source:

• Inline truncation — | head -30 on commands invoked by Claude or by Hooks.
• Transparent rewriting — RTK (Rust Token Killer) wraps commands via Hooks and emits a one-line summary (e.g. ✓ cargo test: 262 passed (1 suite, 0.08s)) so Claude only sees the decision-relevant signal (2026-04-27-claude-code-architecture-governance-engineering).

Compaction trap

Default summarization prunes “re-readable” content first — meaning old tool output gets dropped along with the architecture decisions and constraint rationale embedded around it. Three recoveries from the sources:

• Declare a ## Compact Instructions block in claude-md naming what compaction must preserve in priority order.
• Prefer the HANDOFF.md pattern: have Claude write a handoff doc (current state / what was tried / what worked / dead ends / next steps), then start a fresh session pointed at that file. Doesn’t depend on summarization quality (2026-04-27-claude-code-architecture-governance-engineering).
• Three compression strategies named in 2026-04-27-agent-principles-architecture-engineering:

Identifiers (UUIDs, hashes, IPs, ports, URLs, filenames) must stay byte-identical through any compression step — one digit off in a PR number breaks every downstream tool call.

Codex’s two compaction paths (and the actual prompts)

2026-04-27-codex-context-compaction-investigation (Kangwook Lee, Mar 2026) gives the wiki its first concrete production-grade compaction implementation. The same codex CLI runs two distinct paths, gated by which model is on the other end:

A 35-line Python probe (two API calls — compact() poisons the blob, create() reads the leaked prompts back) shows the two paths use near-identical prompts. The pipeline:

compact() : SYSTEM_PROMPT + COMPACTION_PROMPT + USER_INPUT
            → compactor LLM summarizes → server encrypts (Fernet AES-128-CBC + HMAC-SHA256)
            → ENCRYPTED_BLOB
create()  : SYSTEM_PROMPT + HANDOFF_PROMPT + DECRYPTED_BLOB + NEW_USER_MESSAGE
            → main model resumes

The extracted compaction prompt (server-side):

“You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task. Include: Current progress and key decisions made; Important context, constraints, or user preferences; What remains to be done (clear next steps); Any critical data, examples, or references needed to continue. Be concise, structured, and focused on helping the next LLM seamlessly continue the work.”

The extracted handoff prompt (prepended to the decrypted blob on resume):

“Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis.”

Two takeaways for the wiki:

• Shape of a real compaction prompt. Priorities + structure + audience framing — what to keep, in what order, for whom. This corroborates the ## Compact Instructions block recommended on claude-md above; the OpenAI compactor prompt is essentially a baked-in version of the same pattern, applied at the platform level instead of per-project.
• The handoff prompt is the missing piece the Compaction trap section above didn’t name explicitly. After compaction, the resumed model needs to be told what it’s reading — otherwise the summary lands ambiguous and the model may treat a third-party compactor’s output as its own prior thinking. Codex frames this as “another language model started to solve this problem”; claude-code‘s HANDOFF.md pattern does the same job at the file level.

The author flags (and the wiki inherits) the open question: why does Codex split between local-LLM compaction and encrypted-API compaction when the prompts are nearly identical? His guess — the encrypted blob may also carry compacted tool results, not just the dialogue summary — is plausible but unverified. Treat the extracted prompts as evidence-of-current-behavior, not published spec.

Operating habits

• Watch /context before the system auto-compacts.
• Task switch → /clear; same task new phase → /compact.
• The act of starting a new session is often cheaper than another round of prompt iteration on the same one.

Filesystem as the context interface

A pattern Cursor calls Dynamic Context Discovery, also surfaced in 2026-04-27-agent-principles-architecture-engineering: don’t push large outputs into context — write them to disk and let the Agent retrieve via grep / rg / scripts on demand. Tool writes a file; Agent reads the file; developer can also inspect it directly. Same instinct applies to compaction: don’t drop history, write it to a file and have the summary reference the path.

Cursor reportedly saw a 46.9% reduction in total token use on MCP-heavy tasks after moving tool descriptions to a file-backed index where the Agent reads tool definitions only when needed (corroborated in agent-computer-interface Tool Search section). This is the same idea: swap “everything in context” for “index in context, body on disk”.

”Context is a scarce resource” — primary citation

2026-04-27-harness-engineering-codex-agent-first (OpenAI codex team, Apr 2026) names this as their first lesson and gives it a usable framing. Quoting the four reasons the team’s “one big AGENTS.md” attempt failed:

• Context is a scarce resource. A giant instruction file crowds out task content, code, and relevant documentation — so the agent either misses critical constraints or starts optimizing for the wrong ones.
• Too much guidance becomes ineffective. “When everything is important, nothing is.” The agent ends up local-pattern-matching instead of consciously navigating.
• It rots immediately. A monolithic manual becomes a graveyard of stale rules; the agent can’t tell which ones are still in force.
• It’s hard to verify. A single blob doesn’t fit mechanical checks (coverage, freshness, ownership, cross-link).

The replacement they ship — AGENTS.md as ~100-line table of contents with structured docs/ behind it — is the same instinct as the “loading tiers” table above, surfaced from a fully-agent-driven codebase rather than a claude-code one. Convergent evidence: same failure mode, same prescription, two different teams.

Context engineering as optimization target

2026-07-07-harness-engineering-self-improvement (lilian-weng, Jul 2026) frames context engineering as one level in the recursive-self-improvement progression (prompts → structured context → workflow → harness code → optimizer code) and surveys two systems that automate context optimization:

ACE (Agentic Context Engineering) — Zhang et al. 2025

Treats context as an evolving playbook rather than an increasingly lengthening prompt. Three components maintain a logbook of bullet points (identifier + description):

1. Generator: produces task trajectories, referencing bullet points.
2. Reflector: distills insights from successful and failed trajectories.
3. Curator: updates structured context with incremental, itemized entries.

Key design: the curator does not rewrite a full prompt blob. It outputs structured bullets merged with deterministic logic — preventing context collapse and brevity bias during iterative rewrites. Items are refined and deduplicated periodically.

MCE (Meta Context Engineering) — Ye et al. 2026

Separates the mechanism (how to manage context) from the artifact content (what is in context). Bi-level optimization:

• Inner: base-level context engineer optimizes context function $c_s$ given skill $s$.
• Outer: meta-level agent evolves the skill via agentic crossover over skill database ${\mathscr{H}}_{k-1}$.

A skill $s$ defines a context function $c_s=({\rho }_s,F_s)$ where ${\rho }_s$ = static components (prompts, knowledge bases, code libraries) and $F_s$ = dynamic operators (search, selection, filtering, formatting).

MCE does not enforce heuristic rules for context structure (unlike ACE). It uses free-form skills and evolves skill + skill-conditioned context iteratively. Implementation uses standard coding-agent tools: {Read, Write, Edit, Bash, Glob, Grep, TodoWrite}.

Both ACE and MCE represent the direction Weng predicts: context engineering will and should become a core part of intelligence, rather than staying in the software system layer. As agents become more autonomous, memory grows, and managing it becomes as important as raw model capability.

Cross-references

• harness: context engineering is the feedback signal shaping work — what the model sees is what it can reason about.
• agent-memory: the four-type memory model is what populates the layered tiers above.
• prompt-caching: the resident-layer-stability rule isn’t only about token cost — it protects the prefix cache.
• codebase-as-system-of-record: the content-side discipline — context can only carry what exists in the repo to begin with.
• agent-legibility: the audience-side framing — context engineering is one mechanism for making the system legible to the agent.
• long-running-agents: compaction is the mechanism that lets sessions outlive the context window — see the Codex’s two compaction paths section above for the empirical pipeline.
• recursive-self-improvement: context engineering as one rung in the RSI ladder.
• meta-harness: Meta-Harness extends context optimization to full harness-code optimization.