How to Use the QMD --index Option to Manage Separate Knowledge Bases with Named Indexes

Use qmd --index <name> before any subcommand to isolate documents, embeddings, and collections into separate SQLite databases and YAML configuration files, enabling multiple independent knowledge bases.

The qmd CLI tool from the tobi/qmd repository supports running multiple isolated knowledge bases through the QMD --index option. By specifying a named index, you create distinct storage backends for different projects, ensuring that document collections, vector embeddings, and search queries remain completely isolated from one another.

How the --index Option Works

When you append --index <name> to any QMD command, the CLI switches two critical storage components to use the specified name instead of the default "index".

SQLite Database Storage

The vector database and document metadata reside in a SQLite file whose path is determined by the index name. In src/qmd.ts (lines 2101-2105), the setIndexName() function captures the CLI flag value and stores it for later use by getDbPath().

The actual path resolution occurs in src/store.ts within the getDefaultDbPath() function:

export function getDefaultDbPath(indexName: string = "index"): string {
  if (process.env.INDEX_PATH) return process.env.INDEX_PATH;
  if (!_productionMode) {
    throw new Error("Database path not set…");
  }
  const cacheDir = process.env.XDG_CACHE_HOME || resolve(homedir(), ".cache");
  const qmdCacheDir = resolve(cacheDir, "qmd");
  mkdirSync(qmdCacheDir, { recursive: true });
  return resolve(qmdCacheDir, `${indexName}.sqlite`);
}

By default, this creates ~/.cache/qmd/<name>.sqlite. You can override this location by setting the INDEX_PATH environment variable.

Collections Configuration

Each index maintains its own YAML configuration file that maps collection names to source directories and file patterns. In src/collections.ts (lines 60-63), the setConfigIndexName() function reads the same --index flag and updates the target configuration path.

The getConfigFilePath() function constructs the final location:

function getConfigFilePath(): string {
  return join(getConfigDir(), `${currentIndexName}.yml`);
}

This results in ~/.config/qmd/<name>.yml for each named index, completely isolating collection definitions between knowledge bases.

Practical Examples for Managing Multiple Knowledge Bases

The following commands demonstrate how to create and use separate named indexes for different projects.

Create a research-focused knowledge base:

# Initialize the "research" index with a papers collection

qmd --index research collection add ./papers --name papers --mask "**/*.md"

# Build the vector index for research documents

qmd --index research update

# Query the research knowledge base

qmd --index research query "transformer architectures"

Create a separate personal knowledge base:

# Initialize the "personal" index

qmd --index personal collection add ~/notes --name notes

# Index personal documents

qmd --index personal update

# Search personal notes - completely isolated from research data

qmd --index personal search "budget 2024"

Use the default index when no specific project context is needed:

# These commands operate on ~/.cache/qmd/index.sqlite

qmd collection list
qmd query "quick start guide"

Key Implementation Files

Understanding these source files helps clarify how the --index option creates isolation:

File	Function	Role
src/qmd.ts	setIndexName(), setConfigIndexName()	CLI entry point that parses the --index flag and initializes both database and configuration paths.
src/store.ts	getDefaultDbPath()	Resolves the SQLite database location based on the index name, respecting XDG_CACHE_HOME and INDEX_PATH overrides.
src/collections.ts	setConfigIndexName(), getConfigFilePath()	Manages the per-index YAML configuration that defines collections and their source directories.

Summary

• The QMD --index option creates completely isolated knowledge bases by switching both the SQLite database and YAML configuration files to use the specified name.
• Database files default to ~/.cache/qmd/<name>.sqlite and can be overridden via the INDEX_PATH environment variable.
• Collection configurations are stored separately at ~/.config/qmd/<name>.yml, ensuring that directory mappings and file patterns remain distinct between projects.
• Always specify the same --index <name> flag before subcommands (collection, update, query, search) to maintain context within a specific knowledge base.

Frequently Asked Questions

What happens if I omit the --index flag?

If you do not specify --index, QMD defaults to using the index name "index". This creates or uses ~/.cache/qmd/index.sqlite for the database and ~/.config/qmd/index.yml for collections. All operations affect this default knowledge base unless you explicitly switch indexes.

Can I use environment variables instead of the --index flag?

Yes. While --index controls both the database name and config file, you can override the database location specifically by setting the INDEX_PATH environment variable to a full file path. However, this does not change the collections configuration file location, which still follows the --index value or defaults to "index".

Is it safe to delete an index file to start fresh?

Yes. Since each index is self-contained in its own SQLite file (~/.cache/qmd/<name>.sqlite) and YAML file (~/.config/qmd/<name>.yml), you can safely delete these files to reset that specific knowledge base without affecting other indexes. Simply remove the files and re-run qmd --index <name> collection add to recreate the index from scratch.

How do I list all available indexes?

QMD does not currently provide a built-in command to enumerate all existing index files. You can manually list the contents of ~/.cache/qmd/ (for SQLite databases) and ~/.config/qmd/ (for YAML configurations) to see which index names exist on your system. Each <name>.sqlite or <name>.yml file represents a distinct knowledge base.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}