Context Engineering Lessons from Building Manus

I just read an excellent deep dive from the Manus team about context engineering for AI agents, and it’s packed with practical insights that anyone building AI systems should know about.

The Core Insight

The Manus post¹ opens with a striking observation: “Most agent failures are not model failures anymore, they are context failures.” We’ve moved past the era where model limitations were the primary bottleneck. Today’s models are remarkably capable—the challenge is giving them the right information at the right time.

They define context engineering as “the discipline of designing and building dynamic systems that provides the right information and tools, in the right format, at the right time, to give a LLM everything it needs to accomplish a task.” Notice that word: dynamic. This isn’t about crafting perfect static prompts—it’s about building systems that evolve context throughout an interaction.

The Hidden Meta-Insight: Agents Are REP Loops, Not Brains

After digesting the Manus post more deeply, I realized there’s a fundamental meta-insight that runs throughout their approach but is never explicitly stated: Agents are REP Loops, not brains.

This isn’t a minor technical detail—it’s a complete paradigm shift in how we should think about AI agents. We need to stop thinking of them as autonomous entities with free will and start thinking of them as incredibly powerful REPL systems (Read-Eval-Print Loops):

• Read: The carefully constructed context you provide
• Eval: Based on that context, the agent decides its next action
• Print: It outputs the action and results back into the context, starting the next loop

You’re not teaching a student—you’re writing an input script for a supercomputer. All your work should revolve around making each step of this loop clear, predictable, and debuggable.

The Ultimate Framework: Context Engineering = Memory + Environment + Feedback

The Manus approach reveals a systematic framework built around three pillars:

• Memory: How to efficiently store and retrieve successful and failed experiences, working in harmony with KV-Cache
• Environment: Providing the agent with an interactive, persistent workspace (like a file system)
• Feedback: Injecting the results of actions (whether successful or failed) as input for the next decision cycle

Production Lessons Learned the Hard Way

1. Design for KV-Cache Above All Else

In production AI agents, there’s one metric that matters more than anything: KV-Cache hit rate. Every step your agent takes grows the context massively, while outputs (usually tool calls) stay short. At Manus, this input-to-output token ratio is 100:1. Every cache miss means 10x cost explosion.

The costly mistakes:

• Adding dynamic timestamps to system prompts kills cache hit rates to zero
• Unstable JSON serialization with changing key orders silently breaks caching
• Any character change in prompt prefixes invalidates the entire cache

The only way forward:

• Keep prompt prefixes absolutely stable
• Make context append-only—never modify historical steps
• Ensure deterministic serialization
• Treat your context like a database index that needs optimization

I’m seeing this firsthand in my own rent roll cleaning tool for senior living properties. The Excel analysis instructions stay stable in the prompt prefix, while only the actual property data changes. This append-only approach dramatically reduces costs compared to reconstructing the entire analytical framework for each file - even though each rent roll looks completely different to the LLM despite following similar patterns to human eyes.

2. Mask Tools, Don’t Remove Them

When an agent’s tool library grows large, it gets “confused” and picks wrong tools. The natural instinct is to dynamically load only relevant tools.

Why this backfires:

• Any change to tool definitions breaks KV-Cache for all subsequent requests
• When historical steps reference “deleted” tools, the model becomes completely confused

The surgical approach: Use masking during decoding to constrain tool selection while keeping all tool definitions stable in context. Control the action space through logit masking, not context manipulation.

3. File System as Infinite Context

Even 128K or 1M context windows get overwhelmed by a single webpage or PDF. Plus, model performance degrades in long contexts.

The breakthrough insight: Treat the file system as your ultimate context store. It’s infinite, persistent, and the agent can manipulate it directly. When content is too long, remove it from context but preserve the file path. This “recoverable compression” maintains access to information without permanent loss.

4. Use “Recitation” to Control Attention

In complex tasks requiring 50+ tool calls, models easily drift from original goals due to the “lost-in-the-middle” problem.

The attention hack: Force the agent to create and continuously update a todo.md file. Each step requires rewriting this file, which effectively “recites” the global plan to the end of context, keeping core objectives in the model’s immediate attention span.

5. Keep Failures in Context

When agents fail, our instinct is to clean up the “embarrassing” records and retry.

Why this is counterproductive: You’re paying for the model to repeat the same mistakes. Without failure context, it can’t learn from errors.

The learning approach: Preserve error messages, stack traces, and failed attempts as “observation results” in context. When the model sees “I tried A and failed with error X,” it can reflect and choose B instead.

The Meta-Lesson: Context Engineering is Experimental Science

Perhaps the most important takeaway from the Manus experience is that context engineering is fundamentally experimental. We’re not trying to design perfect context upfront—we’re building systems that can evolve and improve their context management over time.

This means prioritizing adaptability over perfection, treating context as a “dynamic, learnable environment.” The REP Loop paradigm reinforces this: each iteration gives you data about what works and what doesn’t, enabling continuous refinement of your context engineering approach.

The future belongs to teams that master this experimental mindset, treating every agent interaction as a source of learning about better context design.