1# Reference: Manus Context Engineering Principles
2 
3This skill is based on context engineering principles from Manus, the AI agent company acquired by Meta for $2 billion in December 2025.
4 
5## The 6 Manus Principles
6 
7### Principle 1: Design Around KV-Cache
8 
9> "KV-cache hit rate is THE single most important metric for production AI agents."
10 
11**Statistics:**
12- ~100:1 input-to-output token ratio
13- Cached tokens: $0.30/MTok vs Uncached: $3/MTok
14- 10x cost difference!
15 
16**Implementation:**
17- Keep prompt prefixes STABLE (single-token change invalidates cache)
18- NO timestamps in system prompts
19- Make context APPEND-ONLY with deterministic serialization
20 
21### Principle 2: Mask, Don't Remove
22 
23Don't dynamically remove tools (breaks KV-cache). Use logit masking instead.
24 
25**Best Practice:** Use consistent action prefixes (e.g., `browser_`, `shell_`, `file_`) for easier masking.
26 
27### Principle 3: Filesystem as External Memory
28 
29> "Markdown is my 'working memory' on disk."
30 
31**The Formula:**
32```
33Context Window = RAM (volatile, limited)
34Filesystem = Disk (persistent, unlimited)
35```
36 
37**Compression Must Be Restorable:**
38- Keep URLs even if web content is dropped
39- Keep file paths when dropping document contents
40- Never lose the pointer to full data
41 
42### Principle 4: Manipulate Attention Through Recitation
43 
44> "Creates and updates todo.md throughout tasks to push global plan into model's recent attention span."
45 
46**Problem:** After ~50 tool calls, models forget original goals ("lost in the middle" effect).
47 
48**Solution:** Re-read `task_plan.md` before each decision. Goals appear in the attention window.
49 
50```
51Start of context: [Original goal - far away, forgotten]
52...many tool calls...
53End of context: [Recently read task_plan.md - gets ATTENTION!]
54```
55 
56### Principle 5: Keep the Wrong Stuff In
57 
58> "Leave the wrong turns in the context."
59 
60**Why:**
61- Failed actions with stack traces let model implicitly update beliefs
62- Reduces mistake repetition
63- Error recovery is "one of the clearest signals of TRUE agentic behavior"
64 
65### Principle 6: Don't Get Few-Shotted
66 
67> "Uniformity breeds fragility."
68 
69**Problem:** Repetitive action-observation pairs cause drift and hallucination.
70 
71**Solution:** Introduce controlled variation:
72- Vary phrasings slightly
73- Don't copy-paste patterns blindly
74- Recalibrate on repetitive tasks
75 
76---
77 
78## The 3 Context Engineering Strategies
79 
80Based on Lance Martin's analysis of Manus architecture.
81 
82### Strategy 1: Context Reduction
83 
84**Compaction:**
85```
86Tool calls have TWO representations:
87├── FULL: Raw tool content (stored in filesystem)
88└── COMPACT: Reference/file path only
89 
90RULES:
91- Apply compaction to STALE (older) tool results
92- Keep RECENT results FULL (to guide next decision)
93```
94 
95**Summarization:**
96- Applied when compaction reaches diminishing returns
97- Generated using full tool results
98- Creates standardized summary objects
99 
100### Strategy 2: Context Isolation (Multi-Agent)
101 
102**Architecture:**
103```
104┌─────────────────────────────────┐
105│         PLANNER AGENT           │
106│  └─ Assigns tasks to sub-agents │
107├─────────────────────────────────┤
108│       KNOWLEDGE MANAGER         │
109│  └─ Reviews conversations       │
110│  └─ Determines filesystem store │
111├─────────────────────────────────┤
112│      EXECUTOR SUB-AGENTS        │
113│  └─ Perform assigned tasks      │
114│  └─ Have own context windows    │
115└─────────────────────────────────┘
116```
117 
118**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.
119 
120### Strategy 3: Context Offloading
121 
122**Tool Design:**
123- Use <20 atomic functions total
124- Store full results in filesystem, not context
125- Use `glob` and `grep` for searching
126- Progressive disclosure: load information only as needed
127 
128---
129 
130## The Agent Loop
131 
132Manus operates in a continuous 7-step loop:
133 
134```
135┌─────────────────────────────────────────┐
136│  1. ANALYZE CONTEXT                      │
137│     - Understand user intent             │
138│     - Assess current state               │
139│     - Review recent observations         │
140├─────────────────────────────────────────┤
141│  2. THINK                                │
142│     - Should I update the plan?          │
143│     - What's the next logical action?    │
144│     - Are there blockers?                │
145├─────────────────────────────────────────┤
146│  3. SELECT TOOL                          │
147│     - Choose ONE tool                    │
148│     - Ensure parameters available        │
149├─────────────────────────────────────────┤
150│  4. EXECUTE ACTION                       │
151│     - Tool runs in sandbox               │
152├─────────────────────────────────────────┤
153│  5. RECEIVE OBSERVATION                  │
154│     - Result appended to context         │
155├─────────────────────────────────────────┤
156│  6. ITERATE                              │
157│     - Return to step 1                   │
158│     - Continue until complete            │
159├─────────────────────────────────────────┤
160│  7. DELIVER OUTCOME                      │
161│     - Send results to user               │
162│     - Attach all relevant files          │
163└─────────────────────────────────────────┘
164```
165 
166---
167 
168## File Types Manus Creates
169 
170| File | Purpose | When Created | When Updated |
171|------|---------|--------------|--------------|
172| `task_plan.md` | Phase tracking, progress | Task start | After completing phases |
173| `findings.md` | Discoveries, decisions | After ANY discovery | After viewing images/PDFs |
174| `progress.md` | Session log, what's done | At breakpoints | Throughout session |
175| Code files | Implementation | Before execution | After errors |
176 
177---
178 
179## Critical Constraints
180 
181- **Single-Action Execution:** ONE tool call per turn. No parallel execution.
182- **Plan is Required:** Agent must ALWAYS know: goal, current phase, remaining phases
183- **Files are Memory:** Context = volatile. Filesystem = persistent.
184- **Never Repeat Failures:** If action failed, next action MUST be different
185- **Communication is a Tool:** Message types: `info` (progress), `ask` (blocking), `result` (terminal)
186 
187---
188 
189## Manus Statistics
190 
191| Metric | Value |
192|--------|-------|
193| Average tool calls per task | ~50 |
194| Input-to-output token ratio | 100:1 |
195| Acquisition price | $2 billion |
196| Time to $100M revenue | 8 months |
197| Framework refactors since launch | 5 times |
198 
199---
200 
201## Key Quotes
202 
203> "Context window = RAM (volatile, limited). Filesystem = Disk (persistent, unlimited). Anything important gets written to disk."
204 
205> "if action_failed: next_action != same_action. Track what you tried. Mutate the approach."
206 
207> "Error recovery is one of the clearest signals of TRUE agentic behavior."
208 
209> "KV-cache hit rate is the single most important metric for a production-stage AI agent."
210 
211> "Leave the wrong turns in the context."
212 
213---
214 
215## Source
216 
217Based on Manus's official context engineering documentation:
218https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
219