What did Manus learn about context engineering for AI agents?

Short answer

In July 2025 Yichao "Peak" Ji of Manus published six lessons from building the Manus agent: design around the KV-cache, mask tools instead of removing them, use the file system as context, recite the plan in a todo.md, keep failed actions in the context, and vary the context so the agent does not copy its own patterns. The thread through all six: stable, append-only context that the agent can extend with files.

The post and why it is cited so often

“Context Engineering for AI Agents: Lessons from Building Manus” was written by Yichao “Peak” Ji of the Manus team and published on July 18, 2025. Manus chose to “bet on context engineering” with frontier models instead of training its own agentic model, so it could ship improvements in hours instead of weeks. The post is one of the few accounts from a team running a general agent in production, which is why it keeps coming up next to Anthropic’s and LangChain’s guides. Where those describe strategies, Manus describes costs and failure modes.

The six lessons

Lesson What Manus does Why
1. Design around the KV-cache Stable prompt prefix, append-only context, deterministic serialization, manual cache breakpoints Input outweighs output about 100:1; cached tokens cost a tenth
2. Mask, don’t remove Keep all tools defined, block actions by masking token logits; group tools by prefix like browser_ and shell_ Changing tools breaks the cache and confuses the model
3. Use the file system as context Write large observations to files, keep the URL or path in context Observations are huge and long inputs degrade and cost money
4. Recite the goal Keep and rewrite a todo.md, checking items off A typical task has about 50 tool calls; the goal drifts out of focus
5. Keep the wrong stuff in Leave failed actions and error traces in the context The model adapts when it sees what went wrong
6. Don’t get few-shotted Vary templates, phrasing and order a little Agents imitate repetitive patterns in their own history

1. The KV-cache. An agent loop appends every action and observation to the context, so the input grows fast while the output stays small. Manus reports an average input-to-output ratio of about 100:1. With Claude Sonnet at the time, cached input cost 0.30 USD per million tokens and uncached 3 USD. A timestamp to the second at the top of the system prompt, or JSON whose key order shifts, makes every call a cache miss.

2. Mask, don’t remove. Dynamically loading tools sounds efficient, but tool definitions sit near the front of the context, so any change invalidates the cache for everything after it. Earlier turns may also refer to tools that no longer exist. Manus uses a state machine that constrains which actions the model can pick, through function-calling modes (auto, required, specified) and response prefilling.

3. The file system as context. Even a 128K window falls short when the agent reads web pages and PDFs, and performance drops at long lengths anyway. Manus treats the sandbox file system as “the ultimate context”: unlimited in size and persistent. Its compression is restorable: drop a page’s content but keep its URL, drop a document but keep its path.

Manus’s sandbox documentation shows where that approach ends. Each task gets its own isolated cloud virtual machine, which sleeps when inactive and wakes with its files unchanged. But a sandbox that keeps sleeping may be recycled (7 days on the free plan and 21 on Pro, per the documentation). When the task is reopened, a new sandbox is created: artifacts and uploaded attachments are restored, but “intermediate code and temporary files created during execution will not be restored”. So only the files that count as output or as important project files reliably survive; scratch work in the file system can disappear even within the same task.

4. Recitation. By rewriting its to-do list at each step, the agent pushes the overall goal into the most recent part of the context, which counters the “lost in the middle” effect and drift over long tasks.

5. Keep errors in. Cleaning up failures removes the evidence. A model that sees a failed action and its stack trace shifts away from it.

6. Avoid few-shot ruts. When Manus reviewed a batch of 20 resumes, it fell into a repetitive rhythm and copied its own earlier actions. Small, controlled variation in serialization breaks the pattern.

The common misunderstanding

Many teams read context engineering as compression: summarize, trim, keep the window small. Manus adds a constraint that is easy to miss. Every change to the earlier part of the context has a price, because it breaks the cache. So the Manus approach prefers appending and pointing to files over rewriting history, and it is careful with irreversible compression: anything dropped should be recoverable from a URL or path. That differs in emphasis from the compaction advice in What does Anthropic say about context engineering?, though both agree on storing notes outside the window.

What this means for a team

Lessons 3 and 4 have a team dimension. Files and to-do lists work as memory for one agent in one sandbox; when the task ends, so does the sandbox. Knowledge that should outlive the task, such as how your team handles a recurring kind of request, needs a place outside it that other agents and colleagues can also reach. And lesson 5 applies to people too: corrections that stay in one session teach that session only. See What is context compaction? and How does LangChain approach context engineering?.

Where Bombos fits

Manus shows that the best memory for an agent sits outside the window and is loaded by reference. Bombos is that idea for a whole team: a plugin that gives every AI tool your team uses one shared memory, with team knowledge, rules learned from corrections, and what already sits in mail, documents and repos, retrieved per question and traceable to its source. One person can try it first for their own agents.

Related questions

Why does Manus call KV-cache hit rate the most important metric?

Because agents read far more than they write. Manus reports an input-to-output ratio of about 100:1, and with Claude Sonnet cached input cost 0.30 USD per million tokens against 3 USD uncached at the time. A stable prefix that hits the cache cuts both cost and latency.

Why not just remove tools the agent does not need?

Changing the tool list mid-task invalidates the cache and confuses the model when earlier turns refer to tools that are gone. Manus keeps the tools in place and masks token logits during decoding to allow or block actions.

Isn't it better to hide errors from the agent?

Manus argues the opposite: leave failed actions and their error traces in the context, so the model sees the evidence and avoids repeating the mistake. The author calls error recovery a clear sign of real agentic behavior.

Is this advice specific to Manus?

The examples are, but the principles apply to any agent loop: keep the prefix stable, make context append-only, store large observations in files with a pointer, and keep the goal near the end of the context.

Sources

  1. Context Engineering for AI Agents: Lessons from Building Manus (Yichao "Peak" Ji, July 18, 2025)
  2. Effective context engineering for AI agents (Anthropic, September 2025)
  3. Understanding Manus sandbox: your cloud computer (Manus blog)
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.