III · Tool Use & EnvironmentExperimental·

Synthetic Filesystem Overlay

also known as Virtual Filesystem for Agents, Unified-Tree Data Surface, FS-as-Tool-API

Project heterogeneous enterprise data sources into a single Unix-like tree exposed through filesystem primitives so the agent reuses path semantics it already knows instead of learning a bespoke API per source.

This pattern helps complete certain larger patterns —

specialisesAgent-Computer Interface★— Design the tool surface for an LLM agent specifically, with affordances different from human-facing CLIs.

Context

A team is building an enterprise agent that has to read across many heterogeneous internal systems: Notion, Slack, Google Drive, GitHub, Linear, Jira, email, plus internal databases. Each source has its own authentication, pagination, search dialect, and result shape, and cross-source tasks (a Slack thread plus the linked Notion doc plus the related pull request) are the norm rather than the exception.

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.

Forces

Each source has unique semantics, but a unified surface must hide them.
The agent's strongest navigation priors are filesystem operations, not REST.
Cross-source joins (a Slack thread plus its linked Notion doc plus the related PR) require traversal, not separate tool calls.
Auth, rate limits, and pagination must remain per-source even when the surface is unified.
Lazy enumeration matters: listing all of Slack as a directory cannot fetch every message eagerly.

Example

An on-call engineer asks the assistant to summarize last week's incident. The agent runs find /slack -name '*incident*' -newer 2026-05-12, cats the matching channel transcripts, searches /notion for the linked postmortem template, and lists /github/infra/prs filtered by date. Three sources, one navigation idiom, no per-source SDK calls. The same agent on a new connector (Linear) needs only a new subtree under /linear/ — no new tools, no new prompts.

Diagram

flowchart TD A[Agent] -->|list / find / cat / search / locate_in_tree| IF[Five-primitive interface] IF --> RT[Path-routing layer] RT --> AD1[Slack adapter /slack/...] RT --> AD2[Notion adapter /notion/...] RT --> AD3[Drive adapter /drive/...] RT --> AD4[GitHub adapter /github/...] AD1 --> API1[(Slack API)] AD2 --> API2[(Notion API)] AD3 --> API3[(Drive API)] AD4 --> API4[(GitHub API)] RT -.lazy hydration: list returns paths, cat materialises content.-> A

Solution

Therefore:

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.

What it gives you

One mental model across all sources; new connectors add a subtree, not a new vocabulary.
Reuses the model's filesystem priors instead of training new tool affordances.
Cross-source traversal becomes path concatenation rather than ID translation.
Small primitive set keeps the tool surface tiny even as data grows.
Lazy hydration bounds per-call cost.

What it costs you

Source semantics that do not map to trees (graph-heavy data, time-series streams) must be flattened or hidden.
Path stability becomes a contract — renames in upstream sources can break agent memory of paths.
Permission systems differ per source; a unified path namespace must still enforce per-source ACLs.
Full-text search quality depends on each adapter; uneven coverage frustrates the agent.
Listing very large directories needs careful pagination defaults.

What this pattern forbids. The agent must access enterprise data only through the five primitives — direct per-source API calls are forbidden once the overlay is mounted. It must treat paths as the canonical identifier and not invent paths that locate_in_tree has not validated.

And the patterns that stand alongside it, or against it —

alternative-toModel Context Protocol★★— Standardise how agents discover and call tools so that a tool written once is usable by any conformant agent.
alternative-toTool Discovery★— Let the agent discover available tools at runtime rather than hardcoding the tool list at agent build time.
alternative-toKnowledge Graph Memory★— Persist agent memory as entities and relations in a structured graph so symbolic queries (path, neighbour, type) become possible.
alternative-toNaive-RAG-First✕— Anti-pattern: reach for naive RAG before checking whether the knowledge actually needs retrieval.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance

Source: patterns/synthetic-filesystem-overlay.md on GitHub · commit 4314cd3 · view history
Added to catalog: 2026-05-19
Last updated: 2026-05-21
Contribute: open an issue or PR at github.com/agentpatternscatalog/patterns.