Engineer Context with Filesystem Persistence

Treats the filesystem as a single interface for agents to store, retrieve, and update effectively unlimited context, solving the mismatch between limited context windows and tasks that need more information than fits in one. Its core insight: files enable dynamic context discovery - agents pull relevant context on demand rather than carrying everything statically. Context engineering fails in four predictable ways - needed context missing from the total available context, retrieved context failing to encapsulate what's needed, retrieved context far exceeding what's needed and wasting tokens, or an agent unable to discover niche information buried across many files - and it answers with six concrete solution patterns: writing large tool outputs (e.g. an 8000-token web search result) to a scratch file and returning only a path plus a short summary rather than the full content; persisting a structured plan (a YAML file with steps and status) that the agent re-reads each turn to stay oriented across a long task; having sub-agents write findings directly to files a coordinator reads, instead of passing messages through a "game of telephone" that degrades fidelity; storing skills as files with only names and descriptions in static context, loading full skill content on demand; syncing terminal or log output to files so an agent can grep for errors instead of loading entire histories; and agents writing learned user preferences to their own instruction files for future sessions to load automatically - flagged as an emerging, still-risky pattern needing guardrails against accumulating contradictory instructions.

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

Use it when tool outputs are bloating the context window, agents need to persist state across long trajectories, sub-agents must share information without direct message passing, skills or instructions exceed what fits comfortably in the system prompt, or terminal or log output needs selective querying. Not a fit for single-turn tasks, when context already fits comfortably in the window, when latency is critical since file I/O adds overhead, or with a model too weak to use filesystem tools reliably.

Input: an agent workflow with large tool outputs, long-running plans, multi-agent coordination, or many optional skills. Output: a structured scratch/, memory/, skills/, and agents/ file layout, references returned to the agent instead of raw content, and measured token savings - static-vs-dynamic context ratio, tool-output size before and after offloading, and how often dynamic context actually gets loaded.

Combines ls/glob/grep/read_file-with-line-ranges for structural, exact-match discovery alongside semantic search for conceptual queries. Connects to sibling patterns context-optimization (a form of observation masking), memory-systems (filesystem-as-memory), multi-agent-patterns (isolation via file workspaces), context-compression (file references as lossless compression), and tool-design (tools should return file references for large outputs rather than the content itself), and cites LangChain Deep Agents and Cursor as prior art. Its guidelines also call for implementing cleanup of scratch files to prevent unbounded growth, and for guarding self-modification patterns with validation.

Agent builders hitting context-window limits from large tool outputs, long-horizon tasks, multi-agent coordination, or too many skills who need a concrete filesystem-based pattern rather than cramming everything into the prompt.