filesystem-context

Write tool outputs exceeding roughly 2000 tokens to scratch files and return only a short summary with the file path to the context. The agent can later use grep or line-range reads to retrieve specific sections on demand.

Store the plan in a structured file such as a YAML checklist with step statuses. The agent re-reads this file at the start of each turn or when it needs to re-orient, preventing objectives from being lost to summarization.

Use filesystem patterns when tool outputs are large, tasks span multiple turns, or multiple agents share state. Avoid them for single-turn tasks, when context fits comfortably, or when latency is critical since file I/O adds overhead.

Filesystem search with grep, glob, and line-range reads often outperforms semantic search for technical content like code and API docs where structural patterns matter. Combining both approaches covers conceptual and exact-match queries.

Self-modification lets agents persist learned user preferences across sessions, but it is an emerging pattern. Without validation guardrails, agents can accumulate incorrect or contradictory instructions over time.