State Persistence & Context Memory¶
A critical challenge in AI Engineering is the Context Window Limit. During a long Red Teaming engagement, an LLM will inevitably forget initial reconnaissance data as the conversation history grows.
[!NOTE] The Problem: As an AI enumerates a target, decompiles an APK, and writes an exploit over several hours, it loses track of its original goal and previous failures, leading to looping behavior.
The Solution: Emmu implements Mission Workspaces and a persistent Scratchpad system. The AI is forced to summarize its state to a local Markdown file, effectively creating an infinite external memory drive.
1. Mission Workspaces¶
When you ask Emmu to assess a target, it uses the init_mission_workspace tool to create a dedicated directory on your local disk (e.g., workspace/targets/<target_id>/).
This workspace serves as the absolute source of truth. It holds:
- Recon Data: Output from subfinder, nmap, etc.
- Loot: Extracted databases, decompiled source code, or binaries.
- Exploits: Generated solve.py or bash scripts.
- The Scratchpad: The agent's persistent brain.
Because this data is stored locally, you can securely access, modify, or delete it using your standard OS tools, and the AI will recognize the changes.
2. The Scratchpad Concept¶
The Scratchpad (scratchpad.md) is Emmu's primary defense against context window amnesia.
How the AI uses the Scratchpad:
The Agent's system instructions mandate the use of two specific MCP tools:
1. emmu_read_scratchpad
2. emmu_update_scratchpad
Every 5 execution loops, or before pivoting to a new attack vector, the AI is instructed to call emmu_update_scratchpad and record:
- Current Hypothesis: What is the AI trying to achieve right now?
- Actions Taken: What tools were run, and what were the results?
- Failures: What did not work? (Crucial to prevent the AI from repeating mistakes).
graph LR
A[Task Execution] --> B{Loop Counter > 5?}
B -->|Yes| C[Call emmu_update_scratchpad]
C --> D[(scratchpad.md)]
B -->|No| E[Continue Mission]
F[Context Window Reset] --> G[Call emmu_read_scratchpad]
G --> D
D -->|Inject Summary| G
3. Disaster Recovery¶
Because Emmu is an in-process bridge, application crashes, UI refreshes, or network timeouts could theoretically wipe out an ongoing session.
However, because the AI relies heavily on the scratchpad.md and the Mission Workspace, Disaster Recovery is native.
If a session terminates abruptly, simply restart Emmu and tell the agent:
"Resume work on Target Alpha."
The AI will instinctively call emmu_read_scratchpad("Target Alpha"), ingest its past hypothesis and failures, and continue the attack precisely where it left off, entirely bypassing context window limitations.