filesystem-context

Write tool outputs exceeding roughly 2000 tokens to scratch files and return only a compact summary with the file path. The agent then uses grep or line-range reads to retrieve specific details on demand instead of keeping the full output in message history.

Serialize the plan as structured JSON or YAML with objective, step statuses, and notes, then save it to a file like scratch/current_plan.json. The agent re-reads this file at the start of each turn or after summarization to restore task awareness.

Use it when tool outputs exceed about 2000 tokens, tasks span multiple turns, or multiple agents share state. Avoid it for single-turn tasks, when context fits comfortably in the window, or when file I/O latency is unacceptable.

Each sub-agent writes findings to its own isolated workspace directory, and the coordinator reads those files directly. This preserves full fidelity and avoids the information degradation that occurs in multi-hop message chains.

Self-modification can accumulate incorrect or contradictory instructions over time. Guard it with validation such as entry limits, value length caps, and periodic human review of persisted preferences.

Agents may hold paths from prior turns that no longer exist after refactors or file moves. Always verify file existence before reading a cached path and re-discover files with glob if the check fails.