Skip to main content
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

string
default:"'localhost'"
Host name of the Chroma HTTP server.
number
default:"8000"
Port of the Chroma HTTP server.
boolean
default:"false"
Connect over HTTPS instead of HTTP.
string
required
Name of the existing Chroma collection to mount.
string
default:"'page_slug'"
Chunk metadata key that holds the path of the file a chunk belongs to, relative to the mount root (guides/quickstart.md).
string
default:"'chunk_index'"
Chunk metadata key whose integer orders a file’s chunks; a chunk without one sorts as 0.

Layout

Paths come from the collection’s path tree document, the one with the ID __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.
The search CLI ranks chunks by meaning with Chroma’s vector query. Register it on the workspace:
The score is 1 minus Chroma’s distance, and --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 same ChromaVFS 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 -r and rg: read only the pages with a chunk holding the text, which Chroma’s $contains answers, then match each page as grep does. No match can span two chunks, so it misses nothing. $contains matches case, so -i reads every page.

VFS.md

The VFS.md an agent reads with Chroma mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • Paths are document slugs from the collection’s path tree.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.