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

> Learn to manage separate knowledge bases with named indexes using the QMD --index option. Isolate documents, embeddings, and collections into independent SQLite databases and YAML files. Build multiple knowledge bases easily.

- Repository: [Tobias Lütke/qmd](https://github.com/tobi/qmd)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/tobi/qmd/blob/main/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`](https://github.com/tobi/qmd/blob/main/src/store.ts) within the `getDefaultDbPath()` function:

```typescript
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`](https://github.com/tobi/qmd/blob/main/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:

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

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/tobi/qmd/blob/main/src/qmd.ts) | `setIndexName()`, `setConfigIndexName()` | CLI entry point that parses the `--index` flag and initializes both database and configuration paths. |
| [`src/store.ts`](https://github.com/tobi/qmd/blob/main/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`](https://github.com/tobi/qmd/blob/main/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.