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

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 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.
  • complementsFilesystem as Context★— Use the filesystem as the agent's externalized working memory, writing plans, notes, and large tool outputs to files, dropping them out of the live window, and re-reading on demand.
  • complementsShadow Workspace★— Mirror the workspace into an isolated, version-controlled shadow where the agent makes and reverts edits, surfacing diffs for review and promoting only accepted changes to the real tree.

Neighbourhood

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

References

Provenance