Synthetic Filesystem Overlay

Problem

Designing one agent-friendly tool API per source does not scale: every new connector adds a fresh vocabulary the model has to learn, and the tool count climbs past the point where the agent can choose well between them. Flattening everything into a vector store of chunks loses structure and makes cross-source joins impossible. Meanwhile the model has very strong priors for Unix-like filesystem navigation (list, find, cat, grep) from training data, but no native enterprise source matches those semantics — observations from production logs show agents inventing file-path syntax against APIs where no filesystem actually exists.

Solution

Mount each connector under a deterministic path: /slack/<workspace>/<channel>/<date>/<message>.md, /notion/<workspace>/<page-path>.md, /github/<org>/<repo>/.... Expose five primitives: list (enumerate children, paginated), find (path-pattern matching), cat (fetch a node's content), search (full-text query, optionally scoped to a subtree), and locate_in_tree (resolve an opaque ID to its path). Each primitive translates into source-specific API calls on demand; nodes are virtual until cat. The agent navigates with shell-like idioms — list /slack/eng/, find /notion -name '*onboarding*', search 'incident 2026-05' /slack/eng — and joins results by paths rather than per-source identifiers.

When to use

• Agent must read across many heterogeneous enterprise data sources.
• Cross-source joins are common and ID translation hurts.
• Tool count is climbing past what the model handles cleanly.
• Source data is mostly tree- or document-shaped.