Skip to main content
The Chroma resource exposes an existing ChromaDB collection as text files mounted at a prefix such as /knowledge/. It is useful when you already have a chunked knowledge base in Chroma and want agents to use normal filesystem commands like ls, cat, grep, find, and chroma-query. For collection setup, see Chroma Setup.

​
Config

import os

from mirage import MountMode, Workspace
from mirage.resource.chroma import ChromaConfig, ChromaResource

config = ChromaConfig(
    host=os.environ.get("CHROMA_HOST", "localhost"),
    port=int(os.environ.get("CHROMA_PORT", "8000")),
    ssl=os.environ.get("CHROMA_SSL", "false").lower() == "true",
    collection_name=os.environ["CHROMA_COLLECTION"],
    slug_field=os.environ.get("CHROMA_SLUG_FIELD", "page_slug"),
    chunk_index_field=os.environ.get("CHROMA_CHUNK_INDEX_FIELD", "chunk_index"),
)
resource = ChromaResource(config=config)
ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)
The resource is read-only and does not support snapshots.

​
Filesystem Layout

Chroma paths come from the path tree document stored in the collection with ID __path_tree__. The document body must be a JSON object whose keys are virtual file paths below the mount prefix. 
{
  "README.md": {
    "size": 1024
  },
  "guides/quickstart.md": {
    "size": 4096,
    "updated_at": "2026-01-03T00:00:00Z"
  }
}
Mounted at /knowledge/, this becomes: 
/knowledge/
  README.md
  guides/
    quickstart.md
Mirage infers folders from path segments and stores the tree in the index cache. The size, created_at, and updated_at metadata values are used by tree and listing operations when present.

​
Reading Documents

Each file is assembled from Chroma chunk documents whose metadata slug matches the path. Chunks are sorted by the configured chunk index field and joined with a single newline. 
ls /knowledge/
tree /knowledge/
find /knowledge/ -type f
cat /knowledge/guides/quickstart.md
head -n 20 /knowledge/guides/quickstart.md
tail -n 20 /knowledge/guides/quickstart.md
grep -in "billing" /knowledge/

​
Exact Search with Grep

grep uses Chroma document filtering as a coarse prefilter when possible, then applies Mirage’s grep matching over assembled file text. Scoped paths restrict the candidate files before querying Chroma. 
grep "refund" /knowledge/policies/
grep -i "quickstart" /knowledge/
grep -n "API key" /knowledge/guides/quickstart.md
The chroma-query command calls Chroma’s native vector query API. Use it when semantic similarity matters more than exact text matching. 
chroma-query "how do I get started" /knowledge/
chroma-query --top-k 5 "billing policy" /knowledge/policies/
chroma-query --top-k 3 "API authentication" /knowledge/guides/quickstart.md
Results are emitted one hit per line: 
/knowledge/guides/quickstart.md	0.82	Use an API key to authenticate requests.
Columns are path, score, and chunk text. The score is derived from Chroma’s returned distance as 1 - distance.

​
Cache

The resource uses Mirage’s index cache for the virtual tree. The first directory listing or path resolution fetches __path_tree__; later ls, find, tree, and path resolution reuse the cached tree until the index cache expires or the workspace is recreated. File content is still read from Chroma when commands materialize document text.

​
Examples

Runnable examples live under examples/python/chroma/:
  • chroma.py — command workflow with ls, tree, find, cat, head, tail, grep, and chroma-query.
  • chroma_vfs.py — in-process VFS workflow with os.listdir(), open(), and os.path.*.

​
Shell Commands

CommandNotes
lsList folders and files from the path tree
treePrint the mounted path tree
findSearch the virtual tree by name, type, depth, and size
catRead full file text assembled from Chroma chunks
head / tailRead the first or last lines/bytes
grepExact or regex matching over assembled file text
chroma-queryVector retrieval through Chroma