Filesystem-Based Context Engineering

Filesystem-Based Context Engineering

Use the filesystem as the primary overflow layer for agent context because context windows are limited while tasks often require more information than fits in a single window. Files let agents store, retrieve, and update an effectively unlimited amount of context through a single interface.

Prefer dynamic context discovery -- pulling relevant context on demand -- over static inclusion, because static context consumes tokens regardless of relevance and crowds out space for task-specific information.

When to Activate

Activate this skill 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
• Tasks require more context than fits in the window
• Building agents that learn and update their own instructions
• Implementing scratch pads for intermediate results
• Terminal outputs or logs need to be accessible to agents

Do not activate this skill for adjacent work owned by other skills:

• Semantic cross-session memory, entity tracking, or temporal knowledge graphs: memory-systems.
• Conversation summarization, compaction, or durable handoff wording: context-compression.
• Token-efficiency tactics that do not require file-backed storage: context-optimization.
• Multi-agent topology or handoff protocol design: multi-agent-patterns.

Core Concepts

Diagnose context failures against these four modes, because each requires a different filesystem remedy:

1. Missing context -- needed information is absent from the total available context. Fix by persisting tool outputs and intermediate results to files so nothing is lost.
2. Under-retrieved context -- retrieved content fails to encapsulate what the agent needs. Fix by structuring files for targeted retrieval (grep-friendly formats, clear section headers).
3. Over-retrieved context -- retrieved content far exceeds what is needed, wasting tokens and degrading attention. Fix by offloading bulk content to files and returning compact references.
4. Buried context -- niche information is hidden across many files. Fix by combining glob and grep for structural search alongside semantic search for conceptual queries.

Use the filesystem as the persistent layer that addresses all four: write once, store durably, retrieve selectively.

Detailed Topics

The Static vs Dynamic Context Trade-off

Treat static context (system instructions, tool definitions, critical rules) as expensive real estate -- it consumes tokens on every turn regardless of relevance. As agents accumulate capabilities, static context grows and crowds out dynamic information.