search

search asks a mount’s own search to rank its records for a query: Dify’s retrieval API, Chroma’s and Qdrant’s vector queries, mem0’s memory search and LanceDB’s vector search. Use it when meaning matters; grep and rg still match exact text.

Setup

search has no account config. It searches the mounts it is pointed at, so register it on a workspace that mounts a store:

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.search import SEARCH
from mirage.vfs.chroma import ChromaConfig, ChromaVFS

vfs = ChromaVFS(ChromaConfig(collection_name="docs"))
ws = Workspace({"/knowledge/": vfs}, mode=MountMode.READ)
ws.register_cli("search", SEARCH)
await ws.shell('search "how do I get started" /knowledge/')

Mounting a store does not register search. For YAML registration, see the CLI overview:

clis:
  search:
    cli: search

Supported commands

Run search --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`search`	Rank the records of a search mount for a query

Usage

search "how do I reset my password" /knowledge/
search --top-k 5 "billing policy" /knowledge/policies/ /knowledge/guides/
search --threshold 0.4 "quickstart" /knowledge/guides/*.md

Argument	Meaning
`QUERY`	The text to rank records by.
`PATH ...`	Folders, files or globs to search; the working directory when none is given. Several are ranked as one query when one mount serves them all.
`--top-k N`	The most hits to print, 1 or more. Absent, the mount’s default: 10, or the config’s `search_limit` on Qdrant and LanceDB and `default_search_limit` on mem0.
`--threshold F`	The score a hit must reach, or on LanceDB the largest distance it may have; `0` keeps every hit.
`--method M`	`semantic`, the default. Dify also takes `fulltext`, `hybrid` and `keyword`.

Each hit prints its path, then its score where the store ranks, then the record’s text:

/knowledge/policies/refunds:0.82
Refunds are allowed within 30 days.

A file the session cannot see is never printed.

Mounts

Mount	Searches with	`--threshold`
Dify	The dataset retrieval API	Dify’s score, from 0 to 1
Chroma	Chroma’s vector query	1 minus Chroma’s distance
mem0	mem0’s memory search	mem0’s score, from 0 to 1
Qdrant	Qdrant’s vector query	Qdrant’s score
LanceDB	LanceDB’s vector search	The largest distance kept

A custom VFS joins the list by implementing search.

Errors

Line	Exit	Prints
No query, an empty one, `--top-k` below 1, an unknown option, or a value that is not a number	2	`search: query is required`, `search: top-k must be positive`, or the option error and `Try 'search --help' for more information.`
A value the mount does not take, such as `--method keyword` on Chroma or `--threshold 1.5` on Dify	1	The mount’s reason, such as `search: only the 'semantic' method is supported`
A path that does not exist	1	`search: /knowledge/nope: No such file or directory`
A path on a mount without search	1	`search: /data: Operation not supported`

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Setup

Supported commands

Usage

Mounts

Errors

​Setup

​Supported commands

​Usage

​Mounts

​Errors

Setup

Supported commands

Usage

Mounts

Errors