PulseFlow Tecnologia
← Insights
·7 min read·framework-playbook·context-engineering·kv-cache·ai-agents
PulseFlow Tecnologia

A context engineering playbook for product and engineering teams

Manus documented, with real production numbers, what context engineering actually means when an agent runs at scale. The core lesson right away is about cost: "KV-cache hit rate is the single most important metric" for production agents - with Claude Sonnet, a cached token costs $0.30 per million tokens versus $3 without caching, a 10x difference, and Manus's average input-to-output ratio is roughly 100:1. That completely reorders the priority for anyone designing an agent's context: before thinking about "what to put in the prompt," you need to think about "what won't invalidate the cache."

Prefix stability is a recipe, not a detail

A common, costly mistake: putting a precise timestamp at the start of the prompt. "Even a single-token difference invalidates the cache" for every token that follows. The recommended practice is keeping the prompt prefix stable, using append-only context, and explicitly marking cache breakpoints - only where they're actually needed.

Mask tools, don't remove them

Dynamically adding or removing tools seems like a good way to keep context lean, but it breaks the KV-cache with every change. The alternative Manus uses is a state machine with logit masking: actions are named with consistent prefixes (browser_, shell_), which lets you restrict which actions are available at any given moment without modifying the tool definitions themselves.

Files as external memory

Instead of trying to keep everything inside the context window, the agent learns to read and write files on demand - "externalized structured memory." Compression strategies keep URLs and paths to restore information later, without losing data. This works around both context-size limits and the performance degradation that happens with very long inputs.

Recitation: keeping the goal at the end of the context

A typical Manus task requires around 50 tool calls - enough time for an agent to lose the thread. The fix is maintaining a todo.md file that's continuously updated, "reciting objectives at the end of the context" to keep the overall plan inside the model's most recent attention window.

Errors belong in the context, not the trash

A common instinct is to clean failed actions out of the context. Manus recommends the opposite: leaving failed actions visible lets the model "implicitly update its internal beliefs." Erasing the error removes the evidence it happened - and context with errors improves task recovery, it doesn't hurt it.

Watch out for repetitive "few-shot" patterns

Models imitate patterns they see in context. A context that's too uniform - the same few examples repeated - causes "drift, over-generalization, or hallucination." The fix is introducing deliberate, structured variation in serialization, phrasing, and ordering, to break the repetitive pattern.

The playbook's ten phases

Combining these production lessons with context-engineering practice:

  1. Source mapping - what enters the context and where it comes from
  2. Knowledge classification - what's fixed, what's dynamic
  3. Prioritization - what stays in the stable prefix, what gets appended
  4. Retrieval - files as external memory, not just the context window
  5. Compression - keeping references (URLs, paths), not raw content
  6. Updating - reciting objectives to maintain focus on long tasks
  7. Validation - preserving errors in context, not erasing them
  8. Cost - cache hit rate as a central metric, not an afterthought
  9. Observability - measuring where the cache breaks and why
  10. Review - checking whether context examples have become too repetitive a pattern

Sources