ChromaVFS mounts one ChromaDB collection, read-only, as a tree of text files:
each file is its chunks joined in order. Set up the collection’s shape as in Chroma setup.
Install
Configure
ssl: true reaches the server over HTTPS. A collection whose chunks name their
file and position with keys other than page_slug and chunk_index sets
slugField and chunkIndexField.
Fields
Chunk metadata key that holds the path of the file a chunk belongs to, relative to the mount root (
guides/quickstart.md).Chunk metadata key whose integer orders a file’s chunks; a chunk without one sorts as
0.Layout
__path_tree__: a JSON object whose keys are file paths below the mount.
Folders come from the / in those paths. /knowledge/guides/quickstart.md is
every chunk whose page_slug is guides/quickstart.md.
Behavior
- Read-only: no command changes the collection.
- Pages: a file is its chunks sorted by chunk index and joined by line breaks.
- Tree refresh: the path tree is fetched on the first listing and reused
until the index expires, so a change to
__path_tree__shows up after that. File text is always read from Chroma.
Vector search
Thesearch CLI ranks chunks by meaning with
Chroma’s vector query. Register it on the workspace:
--threshold keeps the hits that
reach it. --top-k defaults to 10. --method takes only semantic. Each hit
prints its page and score, then the chunk.
Browser
The sameChromaVFS runs in the browser from @struktoai/mirage-browser.
- The page calls the Chroma server directly, so the server must accept requests from the page’s origin.
Integration
Chroma answers this command through its own API, so fewer pages are read. See Integration.grep -randrg: read only the pages with a chunk holding the text, which Chroma’s$containsanswers, then match each page asgrepdoes. No match can span two chunks, so it misses nothing.$containsmatches case, so-ireads every page.
VFS.md
The VFS.md an agent reads with Chroma mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Paths are document slugs from the collection’s path tree.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.