# Environment Variables That Control Indexing Behavior in Codebase-Memory-MCP

> Master Codebase-Memory-MCP indexing with environment variables like CBM_INDEX_SUPERVISOR and CBM_INDEX_SINGLE_THREAD. Control threading, storage, and more.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-13

---

**Codebase-Memory-MCP exposes eight specific environment variables—including `CBM_INDEX_SUPERVISOR`, `CBM_INDEX_SINGLE_THREAD`, and `CBM_CACHE_DIR`—that govern process wrapping, worker threading, crash recovery, timeouts, and storage paths during repository indexing.**

Codebase-Memory-MCP (CBM) is an MCP server that maintains persistent memory of your codebase through a robust indexing pipeline. These environment variables provide fine-grained control over whether indexing runs safely in isolated child processes or deterministically in-process, how the system recovers from crashes, and where artifacts are stored. Understanding these knobs is essential for configuring CI pipelines, debugging failures, and optimizing performance.

## Process Wrapping with CBM_INDEX_SUPERVISOR

The **`CBM_INDEX_SUPERVISOR`** variable determines whether the indexing pipeline executes inside a supervised child process or directly within the current process.

When set to **`0`**, the supervisor is disabled and indexing occurs **in-process**. This mode eliminates process-spawning overhead and is ideal for deterministic tests where you need predictable execution. When unset or set to any other value, `cbm_index_supervisor_should_wrap()` (defined in [`src/mcp/index_supervisor.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.h) at lines 46–53) returns true, causing the supervisor to spawn a child process that safely isolates indexing operations.

Use in-process mode only when you can guarantee the repository content is safe, as a crashing indexer will bring down the entire process.

## Worker Threading and Crash Recovery

Three variables work together to control concurrency and enable precise crash diagnostics: **`CBM_INDEX_SINGLE_THREAD`**, **`CBM_INDEX_MARKER_FILE`**, and **`CBM_INDEX_QUARANTINE_FILE`**.

### Force Single-Threaded Execution

Setting **`CBM_INDEX_SINGLE_THREAD=1`** forces the pipeline to use exactly one worker thread. This is not merely a performance tweak—it is **required** when using the marker file mechanism that tracks which specific file causes a crash. As implemented in [`src/mcp/index_supervisor.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.h) (lines 77–84), the worker checks this variable before spawning multiple threads.

### Track Crashing Files with CBM_INDEX_MARKER_FILE

When single-threaded mode is active, the **`CBM_INDEX_MARKER_FILE`** variable specifies a writable path where the worker records the **relative path** of the file it is about to process. If the process segfaults, this marker file contains the exact culprit, enabling rapid reproduction and debugging.

### Skip Known Bad Files with CBM_INDEX_QUARANTINE_FILE

The **`CBM_INDEX_QUARANTINE_FILE`** variable points to a newline-delimited list of repo-relative paths that the worker should skip and report as "crash" without actually processing them. This mechanism allows the supervisor to continue indexing the remainder of the repository after isolating problematic files that cause persistent failures.

## Timeout and Restart Policies

Control resilience boundaries using **`CBM_INDEX_WORKER_TIMEOUT_S`** and **`CBM_INDEX_MAX_RESTARTS`**.

### Configure Worker Timeouts

**`CBM_INDEX_WORKER_TIMEOUT_S`** accepts an integer value in seconds that overrides the default worker timeout. According to the implementation in [`src/mcp/index_supervisor.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c) (lines 94–98), this value is converted to milliseconds and used by the supervisor to abort workers that hang during processing. This is particularly useful in CI environments where you want to fail fast rather than wait for default timeouts.

### Limit Restart Attempts

**`CBM_INDEX_MAX_RESTARTS`** caps the number of restart attempts the supervisor will make for a failing worker before giving up and reporting permanent failure. This prevents infinite respawn loops on corrupted repositories. The logic resides in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) (lines 4705–4707), where the integer value is read and enforced during the supervision lifecycle.

## Logging and Cache Configuration

Customize output locations and persistent storage using **`CBM_INDEX_LOG`** and **`CBM_CACHE_DIR`**.

### Override Default Log Paths

By default, CBM writes indexing logs to `<cache_dir>/logs/<project>-<epoch>.log`. Set **`CBM_INDEX_LOG`** to an absolute file path to redirect output to a specific location. This override is processed in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) (lines 4331–4339), making it straightforward to capture logs in containerized or ephemeral CI environments.

### Relocate the Graph Database Cache

**`CBM_CACHE_DIR`** specifies the directory where the graph-DB cache and other persistent indexing artifacts are stored. Changing this variable moves both the index write location and read location, effectively isolating different projects or test runs. This variable is referenced throughout the test suite, including in [`tests/windows/test_ui_drive_listing.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_ui_drive_listing.py) (lines 109–110), demonstrating its use for temporary test sandboxes.

## Practical Configuration Examples

Run a deterministic in-process index for testing:

```bash
CBM_INDEX_SUPERVISOR=0 CBM_CACHE_DIR=/tmp/mycache \
  ./cbm-cli --index-repository myrepo

```

Enable single-threaded mode with crash pinpointing:

```bash
CBM_INDEX_SINGLE_THREAD=1 \
CBM_INDEX_MARKER_FILE=/tmp/marker.txt \
CBM_CACHE_DIR=/tmp/mycache ./cbm-cli --index-repository myrepo

```

Quarantine a known bad file while indexing the rest:

```bash
echo "src/bad_file.c" > /tmp/quarantine.txt
CBM_INDEX_QUARANTINE_FILE=/tmp/quarantine.txt \
CBM_CACHE_DIR=/tmp/mycache ./cbm-cli --index-repository myrepo

```

Shorten worker timeout for faster CI failure detection:

```bash
CBM_INDEX_WORKER_TIMEOUT_S=10 CBM_CACHE_DIR=/tmp/mycache ./cbm-cli --index-repository myrepo

```

Redirect logs to a custom location:

```bash
CBM_INDEX_LOG=/tmp/custom-index.log CBM_CACHE_DIR=/tmp/mycache ./cbm-cli --index-repository myrepo

```

## Summary

- **`CBM_INDEX_SUPERVISOR=0`** disables the supervisor and runs indexing in-process, useful for deterministic tests.
- **`CBM_INDEX_SINGLE_THREAD=1`** is required when using marker files to identify crashing source files.
- **`CBM_INDEX_MARKER_FILE`** and **`CBM_INDEX_QUARANTINE_FILE`** work together to track failures and skip problematic paths during recovery.
- **`CBM_INDEX_WORKER_TIMEOUT_S`** sets the maximum execution time in seconds before the supervisor kills a hung worker.
- **`CBM_INDEX_MAX_RESTARTS`** limits how many times the supervisor attempts to restart a failed worker.
- **`CBM_INDEX_LOG`** overrides the default log file location for the indexing run.
- **`CBM_CACHE_DIR`** changes the root directory for all persistent indexing artifacts and graph-DB storage.

## Frequently Asked Questions

### What happens if I set CBM_INDEX_SINGLE_THREAD without a marker file?

The indexing pipeline will run single-threaded, but you lose the ability to identify which specific file caused a crash. The marker file mechanism requires both variables to be set because the worker writes the current file path to `CBM_INDEX_MARKER_FILE` immediately before processing; without this file, there is no record of the in-progress file at the moment of failure.

### How does CBM_INDEX_WORKER_TIMEOUT_S handle invalid inputs?

The implementation in [`src/mcp/index_supervisor.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/index_supervisor.c) (lines 94–98) converts the string value to an integer representing seconds, then multiplies by 1000 to obtain milliseconds. If the variable is unset, the code falls back to a compiled default. Invalid non-numeric values typically result in the default timeout being used, though you should verify behavior with your specific build.

### Can I use CBM_CACHE_DIR to index multiple repositories simultaneously?

Yes. Each repository should use a distinct `CBM_CACHE_DIR` to prevent index collision and locking conflicts. This isolation is standard practice in the test suites (e.g., [`tests/windows/test_cli_non_ascii_arg.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_cli_non_ascii_arg.py)), where temporary directories ensure parallel test execution does not corrupt shared state.

### Where should CBM_INDEX_QUARANTINE_FILE paths be relative to?

Paths listed in the quarantine file should be **repo-relative**, not absolute. The worker compares these paths against the repository structure when deciding whether to skip a file. Using absolute paths will cause the quarantine mechanism to fail silently because the worker performs relative path matching during the indexing traversal.