strukto-ai--mirage/docs/python/resource/chroma.mdx

---
title: Chroma
icon: database
description: Mount a ChromaDB collection as a read-only virtual filesystem.
---

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](/python/setup/chroma).

## Config

```python
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.

```json
{
  "README.md": {
    "size": 1024
  },
  "guides/quickstart.md": {
    "size": 4096,
    "updated_at": "2026-01-03T00:00:00Z"
  }
}
```

Mounted at `/knowledge/`, this becomes:

```text
/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.

```bash
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.

```bash
grep "refund" /knowledge/policies/
grep -i "quickstart" /knowledge/
grep -n "API key" /knowledge/guides/quickstart.md
```

## Vector Search

The `chroma-query` command calls Chroma's native vector query API. Use it when
semantic similarity matters more than exact text matching.

```bash
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:

```text
/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`](https://github.com/StruktoAI/mirage/blob/main/examples/python/chroma/chroma.py) — command workflow with `ls`, `tree`, `find`, `cat`, `head`, `tail`, `grep`, and `chroma-query`.
- [`chroma_vfs.py`](https://github.com/StruktoAI/mirage/blob/main/examples/python/chroma/chroma_vfs.py) — in-process VFS workflow with `os.listdir()`, `open()`, and `os.path.*`.

## Shell Commands

| Command | Notes |
| ------- | ----- |
| `ls` | List folders and files from the path tree |
| `tree` | Print the mounted path tree |
| `find` | Search the virtual tree by name, type, depth, and size |
| `cat` | Read full file text assembled from Chroma chunks |
| `head` / `tail` | Read the first or last lines/bytes |
| `grep` | Exact or regex matching over assembled file text |
| `chroma-query` | Vector retrieval through Chroma |