Why Anthropic Chose File System Navigation Over Embedding Search
TRIGGER
Agents need to fetch and update their own context dynamically during execution, but embedding-based semantic search is difficult to maintain, less accurate, and opaque about why results were retrieved.
APPROACH
Anthropic's Claude Code uses the file system as the primary context store. When Claude encounters large files (logs, user uploads), it decides how to load content into context using bash commands like `grep` and `tail`. The folder and file structure becomes a form of context engineering—e.g., storing previous conversations in a 'Conversations' folder allows the agent to search through them when needed. Input: file/folder structure + bash tools. Output: relevant context pulled into the agent's working memory on demand.
PATTERN
“"Why did it retrieve that?" is unanswerable with embeddings—the "opaque retrieval trap" where debugging wrong context means staring at similarity scores. File system navigation lets agents inspect, filter, and reason about retrieval. Folder hierarchies encode semantics that stay current without reindexing.”
✓ WORKS WHEN
- Agent tasks require explainable retrieval decisions (debugging why context was or wasn't found)
- Context is naturally hierarchical or categorical (conversations by user, documents by type)
- File operations are fast enough for the latency budget (local SSD, <100ms per operation)
- Agent needs to perform complex filtering that embedding similarity can't express (date ranges, regex patterns, file metadata)
✗ FAILS WHEN
- Query latency budget is under 50ms and corpus exceeds 10k files
- Search requires fuzzy semantic matching across paraphrased content (embeddings excel here)
- Files lack meaningful naming or folder organization to navigate
- Corpus changes rapidly and maintaining file structure is operationally expensive