the fake fs, built on redis

i know its not new, but this is in draft since may and thought ill just post it.

its just a way to fool an agent into giving it a file system but its not really a file system. ill go through the details on how we did it, and inspirations we had when building this for our search agent.

let me ground you on a simple problem why we need an fs when agent is deployed on huge amounts of data: the scale of the data is very high, which can never fit in the context window of the model.

so harnesses made it fs accessible to these models as they find the data they drop it into the fs, and read them based on the need (progressive disclosure).

we also believed that agents only need the grep, cat, ls, and find to be able to retrieve information.

when our search agent wants to find the relevant data from the catalog, which is built using deepagents consumes skills, playbooks, or even reference bundles belongs to a usecase, and are scattered across, there is not one single file/doc which will help you do the job entirely as data can power 100s of usecases. so it was straight forward for us to give it a sandbox with real fs attached directly, but it was too expensive (here meaning latency) and also maintenance cost for us introducing more components.

at ~50k conversations a month, the cost of spinning up a new sandbox for each and attaching a file system doesnt seem to scale well and our main focus was never that, but to solve the retrieval problem of data from a catalog (atlan.com) with 50+ sources.

we found that with the filesystemmiddleware supported by deepagents, you can give fs tools to an agent, which doesnt need to know the underlying store.

we wanted to have this is cheap with a less overhead to focus on the right problems, so we went through a lot of approaches and found interesting learnings from mintlify, and working on same problem fundamentally.

building a virtual filesystem for mintlify’s ai assistant — dens sumesh ( @densumesh )

our version of the problem had one extra wrinkle. mintlify’s assistant is answering questions about docs ,the source material is static, someone already wrote it, the job is retrieval. ours has to do that and generate: a lot of what our search agent hands back (a semantic model, a SQL file, a new skill, or even actual data someone asks it to save) doesn’t exist yet when the conversation starts. so whatever we built needed a read path and a write path, not just a read path.

so what is it, actually. not a filesystem. its a routing table. the agent gets exactly four tools – read, write/edit, ls, grep/glob – same four verbs as your terminal. every call carries a path. A dispatcher looks at the path prefix and forwards the call to whichever backend owns that prefix:

1
2
3
4

/workspace/skills/...     → a cache-in-front-of-object-storage backend (read-only)
/workspace/artifacts/...  → object storage, versioned, durable
/workspace/repo/...       → a repos own storage prefix, mounted only when relevant
/tmp/...                  → a short-lived scratch backend, TTL'd, for handoffs

the agent never learns any of this. it just calls read_file("workspace/skills/refund-authority/SKILL.md") and gets text back. whether that text came from a warm cache, a cold fetch from object storage, or a redis key that expires in an hour is not its problem, and that’s the whole trick.

why redis, and not something else. the honest reason is boring: we already run it. It’s already running in our stack. already gets paged on if it falls over. piping an artifact cache onto it meant zero new components to deploy, zero new failure modes to learn, zero new capacity planning, just a new key prefix on infra that was already there.

progressive disclosure - and it’s not just for skills. the same discipline applies to every tool call and every interaction the agent does, not just the ones about skills. the moment a tool result is too big to usefully keep repeating in the conversation, a wide SQL result, a generated semantic model, a long document the agent just wrote - it gets written out to a virtual path automatically, and the message in the transcript is swapped for a pointer instead. the agent doesn’t ask for this; it just discovers, later, that the same read_file call it already knows how to make will pull the real content back when it actually needs to reference it.

1
2
3
4
5
6

def handle_tool_result(result: str, overflow_path: str) -> str:
    if count_tokens(result) <= TOOL_RESULT_TOKEN_LIMIT:
        return result  # small enough — stays in the conversation

    vfs.write(overflow_path, result)
    return f"[result too large — saved to {overflow_path}]"

we’ve done other optimisations that suit our usecases, which allows the agent to do its job much more efficiently with lesser costs.

we really appreciate whatever deepagents support out of the box, to make harness management very simple and extendable. thanks @LangChain_OSS .