Reference: Manus Context Engineering Principles

Reference: Manus Context Engineering Principles

This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.

The 6 Manus Principles

Principle 1: Design Around KV-Cache

"KV-cache hit rate is THE single most important metric for production AI agents."

Statistics:

• ~100:1 input-to-output token ratio
• Cached tokens: $0.30/MTok vs Uncached: $3/MTok
• 10x cost difference!

Implementation:

• Keep prompt prefixes STABLE (single-token change invalidates cache)
• NO timestamps in system prompts
• Make context APPEND-ONLY with deterministic serialization

Principle 2: Mask, Don't Remove

Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.

Best Practice: Use consistent action prefixes (e.g., browser_, shell_, file_) for easier masking.

Principle 3: Filesystem as External Memory

"Markdown is my 'working memory' on disk."

The Formula:

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

Compression Must Be Restorable:

• Keep URLs even if web content is dropped
• Keep file paths when dropping document contents
• Never lose the pointer to full data

Principle 4: Manipulate Attention Through Recitation

"Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."

Problem: After ~50 tool calls, models forget original goals ("lost in the middle" effect).

Solution: Re-read task_plan.md before each decision. Goals appear in the attention window.

Start of context: [Original goal - far away, forgotten]
...many tool calls...
End of context: [Recently read task_plan.md - gets ATTENTION!]

Principle 5: Keep the Wrong Stuff In

"Leave the wrong turns in the context."

Why:

• Failed actions with stack traces let model implicitly update beliefs
• Reduces mistake repetition
• Error recovery is "one of the clearest signals of TRUE agentic behavior"

Principle 6: Don't Get Few-Shotted

"Uniformity breeds fragility."

Problem: Repetitive action-observation pairs cause drift and hallucination.

Solution: Introduce controlled variation:

• Vary phrasings slightly
• Don't copy-paste patterns blindly
• Recalibrate on repetitive tasks

The 3 Context Engineering Strategies

Based on Lance Martin's analysis of Manus architecture.

Strategy 1: Context Reduction

Compaction:

Tool calls have TWO representations:
├── FULL: Raw tool content (stored in filesystem)
└── COMPACT: Reference/file path only

RULES:
- Apply compaction to STALE (older) tool results
- Keep RECENT results FULL (to guide next decision)

Summarization:

• Applied when compaction reaches diminishing returns
• Generated using full tool results
• Creates standardized summary objects

Strategy 2: Context Isolation (Multi-Agent)

Architecture:

┌─────────────────────────────────┐
│         PLANNER AGENT           │
│  └─ Assigns tasks to sub-agents │
├─────────────────────────────────┤
│       KNOWLEDGE MANAGER         │
│  └─ Reviews conversations       │
│  └─ Determines filesystem store │
├─────────────────────────────────┤
│      EXECUTOR SUB-AGENTS        │
│  └─ Perform assigned tasks      │
│  └─ Have own context windows    │
└─────────────────────────────────┘

Key Insight: Manus originally used todo.md for task planning but found ~33% of actions were spent updating it. Shifted to dedicated planner agent calling executor sub-agents.

Strategy 3: Context Offloading

Tool Design:

• Use <20 atomic functions total
• Store full results in filesystem, not context
• Use glob and grep for searching
• Progressive disclosure: load information only as needed

The Agent Loop

Manus operates in a continuous 7-step loop:

┌─────────────────────────────────────────┐
│  1. ANALYZE CONTEXT                      │
│     - Understand user intent             │
│     - Assess current state               │
│     - Review recent observations         │
├─────────────────────────────────────────┤
│  2. THINK                                │
│     - Should I update the plan?          │
│     - What's the next logical action?    │
│     - Are there blockers?                │
├─────────────────────────────────────────┤
│  3. SELECT TOOL                          │
│     - Choose ONE tool                    │
│     - Ensure parameters available        │
├─────────────────────────────────────────┤
│  4. EXECUTE ACTION                       │
│     - Tool runs in sandbox               │
├─────────────────────────────────────────┤
│  5. RECEIVE OBSERVATION                  │
│     - Result appended to context         │
├─────────────────────────────────────────┤
│  6. ITERATE                              │
│     - Return to step 1                   │
│     - Continue until complete            │
├─────────────────────────────────────────┤
│  7. DELIVER OUTCOME                      │
│     - Send results to user               │
│     - Attach all relevant files          │
└─────────────────────────────────────────┘

File Types Manus Creates

Critical Constraints

• Single-action execution: one tool call per turn
• Plan is required: always know goal, current phase, remaining phases
• Files are memory: context is volatile; filesystem is persistent
• Never repeat failures: if action failed, next action must be different
• Communication is a tool: message types include info, ask, result

Manus Statistics

Key Quotes

"Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."

"if action_failed: next_action != same_action. Track what you tried. Mutate the approach."

"Error recovery is one of the clearest signals of TRUE agentic behavior."

"KV-cache hit rate is the single most important metric for a production-stage AI agent."

"Leave the wrong turns in the context."

Source

Based on Manus's official context engineering documentation: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus