Qdrant

The Qdrant VFS exposes a Qdrant collection as a virtual filesystem mounted at some prefix such as /q/. Group-by payload fields become nested folders, each point becomes a .json payload file (plus a .txt text file and an optional blob), and semantic search is the search CLI, which returns ranked points as canonical file paths. For connection setup (self-hosted, Qdrant Cloud, search), see Qdrant Setup. Install the extra:

pip install "mirage-ai[qdrant]"

Config

from mirage import MountMode, Workspace
from mirage.vfs.qdrant import QdrantConfig, QdrantVFS

config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key="...",
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
    text_field="productDisplayName",
    blob_field="image_b64",
    blob_ext="jpg",
    cloud_inference=True,
    search_limit=5,
)
vfs = QdrantVFS(config)
ws = Workspace({"/fashion/": vfs}, mode=MountMode.READ)

The mapping is config-driven; nothing about the dataset is hardcoded. Point group_by at different payload fields and the folder tree changes.

Field	Description
`timeout` default `30`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`url`	Full URL of the Qdrant server, such as a Qdrant Cloud cluster URL; when set, `host`, `port` and `https` are ignored.
`host` default `'localhost'`	Host name of the Qdrant server when `url` is unset.
`port` default `6333`	Port of the Qdrant server when `url` is unset.
`https` default `False`	Connect to `host` over HTTPS when `url` is unset.
`api_key` secret	Qdrant API key, required by Qdrant Cloud.
`collection`	Collection the mount root shows; unset lists every collection as a top-level folder.
`group_by` default `[]`	Payload fields that become folder levels, one per field in order; dotted paths reach nested keys. Unset puts every point’s files directly under the collection.
`basename_fields` default `[]`	`group_by` fields whose folder names keep only the last path or URL segment of the value; two values with one basename under the same parent are refused as a collision.
`id_field` default `'id'`	Key the point id is written under in a point’s `.json`; it replaces a payload field of that name.
`name_field`	Payload field whose value prefixes each point’s file stem as `<name>__<id>`; unset names files by point id alone.
`text_field`	Payload field served as the point’s `.txt` file and printed by `search`; unset leaves no `.txt`, and `search` returns the `.json`.
`blob_field`	Payload field of raw or base64 bytes served as `<id>.<blob_ext>` and left out of the `.json`; unset adds no blob file.
`blob_ext` default `'bin'`	File extension of the blob file, without the dot.
`vector_field`	Payload field holding a copy of the vector, left out of the `.json`.
`search_limit` default `10`	Results `search` returns when `--top-k` is not given.
`max_rows` default `1000`	Most points one folder listing scrolls; points past it are left out, and a group folder lists only the values those points carry.
`embedding_model` default `'sentence-transformers/all-MiniLM-L6-v2'`	Model the server embeds a `search` query with under `cloud_inference`; it must match the model the stored vectors came from.
`cloud_inference` default `False`	Send the `search` query text to the server to embed, which needs a cluster with inference enabled (Qdrant Cloud). `embed` takes precedence; with neither, `search` refuses the query.
`embed` secret	Async function that turns a `search` query into a vector in-process, `(text: str) -> list[float]`.

Fields marked secret are redacted in snapshots.

Document and chunk lineage

Config fields use Qdrant’s dotted nested-key syntax. For example, a LangChain-style point can be mounted by source document and named by page:

{
  "page_content": "Refunds are processed within 14 days…",
  "metadata": {
    "source": "s3://docs/policies/refund-2026.pdf",
    "page": "004"
  }
}

config = QdrantConfig(
    collection="company_docs",
    group_by=["metadata.source"],
    basename_fields=["metadata.source"],
    name_field="metadata.page",
    text_field="page_content",
)

This produces refund-2026.pdf/004__<point-id>.txt. The readable prefix comes from name_field; the Qdrant point id remains as a stable suffix so duplicate page labels cannot collide and a direct read never depends on a warm listing cache. Only the stem the listing publishes opens: another label in front of the same id reads as absent. A label that is not a string spells as compact JSON (true, 1, 1e-7), the same in Python and TypeScript. basename_fields strips URL/path parents from the named group_by fields. Leave a field out to preserve its complete value in one path-safe segment: / renders as ∕, and a blank or dot-led value is led by ⁄, so every value has its own segment that lists and opens. A basename longer than 255 bytes, which ext4 and APFS refuse, is cut to fit and ends in __ plus the md5 of the whole name, so two long leaves stay two directories. Basenames must be unique within their parent group; Mirage refuses an ambiguous listing instead of silently merging two source documents, and opening a basename directory checks every point of its parent group, so a second source past max_rows is refused rather than hidden.

VFS.md

The VFS.md an agent reads with Qdrant mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`qdrant`, read

`/<path>` layout

This mount is a Qdrant vector database exposed as a filesystem.

At the root each directory is a collection (unless a single collection is pinned
in config). Inside a collection, directories are the configured group-by payload
fields; descending narrows a filter. Each matching point appears as files named
by its id: <id>.json (the full payload), <id>.txt (the embedded source text)
when a text field is configured, and <id>.<ext> (raw blob bytes) when a blob
field is configured, where <id> is the Qdrant point id. The embedding vector is
never shown. Use ls/cd/cat/tree/find/wc/grep/rg as usual.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `qdrant` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `qdrant`, read |

## `/<path>` layout

```text
This mount is a Qdrant vector database exposed as a filesystem.

At the root each directory is a collection (unless a single collection is pinned
in config). Inside a collection, directories are the configured group-by payload
fields; descending narrows a filter. Each matching point appears as files named
by its id: <id>.json (the full payload), <id>.txt (the embedded source text)
when a text field is configured, and <id>.<ext> (raw blob bytes) when a blob
field is configured, where <id> is the Qdrant point id. The embedding vector is
never shown. Use ls/cd/cat/tree/find/wc/grep/rg as usual.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `qdrant` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Every path is translated into a Qdrant query. Descending a folder adds one payload filter; the leaf level lists points.

/                                  # list collections (omitted when `collection` is pinned)
/<collection>/                     # distinct group_by[0] values
  <v1>/                            # distinct group_by[1] where group_by[0]=v1
    .../<vN>/                      # all group-by fields bound -> point files
      <id>.json                    # full payload (the metadata)
      <id>.txt                     # embedded source text (when text_field set)
      <id>.<ext>                   # raw blob / image bytes (when blob_field set)

<id> is the Qdrant point id. When name_field is set, leaf stems instead use <name>__<id>. When collection is set the collection level is elided, so the mount root is that collection:

/fashion/
  Men/
    Shoes/
      White/
        3.json
        3.txt
        3.jpg

Point files

A point is shown as its underlying data in its original format, never as the embedding vector:

<id>.txt is the embedded source text (the text_field value), exactly what the vector was built from.
<id>.json is the full payload as compact JSON (the metadata), with the vector and the raw blob omitted.
<id>.<ext> is the raw blob bytes when blob_field is configured.

$ cat /fashion/Men/Shoes/White/3.txt
Nike Men White Running Sneakers

$ cat /fashion/Men/Shoes/White/3.json
{"gender":"Men","articleType":"Shoes","baseColour":"White","productDisplayName":"Nike Men White Running Sneakers","id":3}

Semantic search

Search is the search CLI, not a path. Register it on the workspace:

from mirage.commands.cli.builtin.search import SEARCH

ws.register_cli("search", SEARCH)

It returns each ranked point as its canonical content path (the .txt, or .json when no text_field is set) annotated with the similarity score, followed by the content:

$ search "white running sneakers" /fashion
/fashion/Men/Shoes/White/3.txt:0.7421
Nike Men White Running Sneakers

Flags: --top-k <n> (default search_limit), --threshold <min-score>, --method semantic (the only supported method; grep/rg stay lexical).

Search embedding

search needs a vector for the query, and the config decides where it comes from. With embed set, an async (text: str) -> list[float] the caller brings, the query is vectorized in-process, so a self-hosted Qdrant works and mirage depends on no model runtime; examples/python/vfs/qdrant/qdrant_vfs.py feeds it a dependency-free bag of words, and any model that returns a vector plugs in the same way. Without it, cloud_inference=True sends the query text to the server, so the cluster must have inference enabled (Qdrant Cloud) and store vectors from the same embedding_model (default sentence-transformers/all-MiniLM-L6-v2). With neither, search refuses the query. The hook never lands in a snapshot: a restored mount asks for a fresh VFS.

Supported commands

All commands delegate to Mirage’s shared implementations.

Command	Behaviour on a Qdrant mount
`ls`	list collections, payload folders, or point files
`cd`	navigate (each level narrows the filter)
`tree`	render the folder hierarchy
`cat`	print a point’s text/JSON, or dump raw blob/image bytes
`stat`	directory vs file, blob size, image mime type
`find`	walk the tree (e.g. `find /fashion -name '*.txt'`)
`grep` / `rg`	lexical search over the text/JSON files (below)
`head` / `tail`	first/last lines of a file
`wc`	count lines/bytes of a file

Integration

What Qdrant answers through its own API, so fewer files are read. Integration explains each command.

Command	On Qdrant
`grep -r`, `rg`	The payload text the listing keeps, for ASCII text. It misses nothing.

A folder listing scrolls every point’s payload anyway, so grep -r and rg scroll each folder once more, as a listing does, and read only the .json and .txt files whose text holds the pattern’s text in any case. A point changed since the last listing is still found. A blob, a .json or .txt over 8 KiB, and every file for a text that is not ASCII are read as usual.

Access pattern

The mount is read-only (MountMode.READ); writes are not supported. The two read modes are:

Browse by payload folders: scroll filters on group_by fields, no embedding.
Search by meaning: the search CLI’s search "<query>" <path> runs vector search and returns canonical point paths.

Folder listings are capped by max_rows. A filtered listing scrolls first and only creates keyword payload indexes for the group_by fields if Qdrant reports one is required, so already-indexed collections work under read-only keys. Keep group_by to low-cardinality fields for large collections.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

Document and chunk lineage

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Point files

Semantic search

Search embedding

Supported commands

Integration

Access pattern

​Config

​Document and chunk lineage

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Point files

​Semantic search

​Search embedding

​Supported commands

​Integration

​Access pattern

Config

Document and chunk lineage

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Point files

Semantic search

Search embedding

Supported commands

Integration

Access pattern