# codebase-memory-mcp Environment Variables: Complete Configuration Reference

> Explore the codebase-memory-mcp environment variables for flexible configuration. Customize binary selection, cache location, logging, tests, and memory profiling without code edits.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: api-reference
- Published: 2026-07-30

---

**TLDR:** codebase-memory-mcp uses environment variables to control binary variant selection, cache storage locations, daemon logging levels, test execution behavior, and memory profiling output, enabling customization without code changes.

The `codebase-memory-mcp` repository implements a Model Context Protocol (MCP) server that manages codebase memory through a persistent graph database. The tool reads **environment variables** at runtime to determine where to store cache files, which binary variant to execute, and how to configure internal testing harnesses. Developers and CI pipelines can leverage these variables to override defaults, simulate failure conditions, and enable detailed profiling.

## Binary Variant and Installation Control

### CBM_VARIANT

In [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) at line 368, the installer checks `CBM_VARIANT` to determine which precompiled binary to download. When set to `ui` (case-insensitive), the tool fetches the UI-enabled build with the `ui-` prefix instead of the default headless variant.

### CBM_DOWNLOAD_URL

The test suite uses `CBM_DOWNLOAD_URL` to intercept automatic downloads. In [`tests/windows/test_windows_update_handoff.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_windows_update_handoff.py) at line 112, setting this variable to a local file URL (e.g., `file:///tmp/fake-release.tar.gz`) or an unreachable endpoint allows tests to simulate network failure conditions or speed up execution by pointing to local fixtures.

## Cache Directory Configuration

### CBM_CACHE_DIR

Test scripts such as [`tests/windows/test_ui_drive_listing.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_ui_drive_listing.py) (line 113) and [`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) (line 71) read `CBM_CACHE_DIR` to override the default graph-DB cache location. This variable directs the test harness to write graph memory data to a specific directory rather than using OS-specific defaults.

### OS-Specific Cache Directories

Production code in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) (lines 324-328) falls back to standard OS environment variables when `CBM_CACHE_DIR` is unset. On Windows, the tool uses `LOCALAPPDATA`; on Unix systems, it respects `XDG_CACHE_HOME`. Additionally, Windows-specific tests utilize `USERPROFILE` to resolve the user's home directory for path validation.

## Daemon and Test Harness Configuration

### CBM_DAEMON_SMOKE_REQUIRE_RUN

Integration tests in [`tests/test_daemon_smoke.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_daemon_smoke.py) (lines 694 and 730) gate expensive daemon startup sequences behind the `CBM_DAEMON_SMOKE_REQUIRE_RUN` flag. When set to `1`, the test runner forces the daemon to start; otherwise, the test is skipped. This allows CI pipelines to selectively enable resource-intensive smoke tests.

### Logging Controls (CBM_LOG_LEVEL and CBM_LOG_FORMAT)

The same smoke test file configures daemon verbosity through `CBM_LOG_LEVEL` (line 783) and output formatting through `CBM_LOG_FORMAT` (line 784). Valid values for level include `info` and `debug`, while format accepts values such as `json` or `text`. These values are passed directly to the daemon's `--log-level` and `--log-format` arguments.

### Worker Process Debugging

The test harness exposes several variables for debugging worker processes:

- **CBM_TEST_HANG_ON** (line 785): When set to a value like `hang_me`, injects a deliberate deadlock to verify the harness can detect and recover from hangs.
- **CBM_TEST_WORKER_DESCENDANT_PID_FILE** (line 786): Specifies the path where the daemon's worker process writes its PID, allowing the test to confirm successful startup.
- **CBM_TEST_WORKER_PROJECT_LOCK_PID_FILE** (line 1502): Similar to the above, but specific to the "project lock" worker process.

## Indexing Behavior Control

### CBM_INDEX_SUPERVISOR

In [`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) (line 87) and [`tests/repro/issue832_rss.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/repro/issue832_rss.py) (line 65), `CBM_INDEX_SUPERVISOR` controls whether indexing runs in-process or via a background supervisor. Setting it to `0` forces deterministic, single-process indexing, while `1` enables the background supervisor. Tests use the `0` setting to ensure reproducible, deterministic execution.

### CBM_INDEX_WORKER_TIMEOUT_S

The [`tests/repro/issue832_rss.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/repro/issue832_rss.py) script (line 66) reads `CBM_INDEX_WORKER_TIMEOUT_S` to configure the timeout in seconds for background indexing workers. Adjusting this value can speed up or slow down tests involving background indexing operations.

## Memory Profiling and Performance Tuning

### CBM_MEM_PROFILE and CBM_MEM_PROFILE_OUT

Memory profiling is controlled through variables read by [`scripts/memlab-report.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/memlab-report.py). Setting `CBM_MEM_PROFILE` to `1` (line 4) enables the low-level profiler, causing the program to write JSONL records to the path specified by `CBM_MEM_PROFILE_OUT` (line 77). The reporting script then consumes this file to generate human-readable summaries.

### Threading Configuration for Vector Generation

The [`scripts/extract_nomic_vectors.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/extract_nomic_vectors.py) script (line 39) respects `OMP_NUM_THREADS` and `MKL_NUM_THREADS` to control parallelism when generating Nomic embeddings. These variables set the thread counts for OpenMP and Intel MKL respectively, allowing users to limit resource consumption or maximize throughput on high-core machines.

## CI and Platform-Specific Variables

### MSYSTEM

The CI helper script [`scripts/run-test-wave.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/scripts/run-test-wave.py) (line 433) checks for the `MSYSTEM` environment variable to detect MSYS/MinGW environments on Windows. When detected and the interpreter reports `os.name != "nt"`, the script toggles Windows-specific code paths to ensure correct behavior under emulation or compatibility layers.

## Practical Configuration Examples

```bash

# Select the UI-enabled binary variant

export CBM_VARIANT=ui
codebase-memory-mcp

# Redirect download tests to a local fixture

export CBM_DOWNLOAD_URL=file:///tmp/fake-release.tar.gz
pytest -k windows_update_handoff

# Enable memory profiling with custom output path

export CBM_MEM_PROFILE=1
export CBM_MEM_PROFILE_OUT=/tmp/profile.jsonl
codebase-memory-mcp
python scripts/memlab-report.py /tmp/profile.jsonl

```

## Summary

- **CBM_VARIANT** controls whether the UI-enabled or headless binary variant is downloaded via [`_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_cli.py) line 368.
- **CBM_CACHE_DIR** overrides the graph-DB cache location in test environments, while `LOCALAPPDATA` and `XDG_CACHE_HOME` provide OS-specific defaults.
- **CBM_DAEMON_SMOKE_REQUIRE_RUN**, **CBM_LOG_LEVEL**, and **CBM_LOG_FORMAT** configure daemon startup and logging verbosity in smoke tests.
- **CBM_INDEX_SUPERVISOR** and **CBM_INDEX_WORKER_TIMEOUT_S** control background indexing behavior for reproducible testing.
- **CBM_MEM_PROFILE** and **CBM_MEM_PROFILE_OUT** enable JSONL memory profiling output for analysis with [`memlab-report.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/memlab-report.py).
- **OMP_NUM_THREADS** and **MKL_NUM_THREADS** limit CPU parallelism during Nomic vector extraction.
- **CBM_DOWNLOAD_URL** and **MSYSTEM** support CI customization and platform detection respectively.

## Frequently Asked Questions

### What is the default cache directory if CBM_CACHE_DIR is not set?

When `CBM_CACHE_DIR` is undefined, the tool derives the cache location from OS-specific environment variables. On Windows, it uses `%LOCALAPPDATA%`; on Linux and macOS, it respects `$XDG_CACHE_HOME`, falling back to `~/.cache` if neither variable is present. This logic is implemented in [`pkg/pypi/src/codebase_memory_mcp/_cli.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py) at lines 324-328.

### How do I force the test suite to run expensive daemon integration tests?

Set `CBM_DAEMON_SMOKE_REQUIRE_RUN=1` before executing the test suite. This variable, checked at lines 694 and 730 of [`tests/test_daemon_smoke.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_daemon_smoke.py), overrides the default skip behavior and forces the daemon to start for comprehensive integration testing. Without this flag, the smoke tests are skipped to conserve CI resources.

### Can I use environment variables to test network failure scenarios?

Yes. By setting `CBM_DOWNLOAD_URL` to an unreachable URL or a local file path (e.g., `file:///tmp/invalid.tar.gz`), you can simulate download failures. The test harness in [`tests/windows/test_windows_update_handoff.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_windows_update_handoff.py) (line 112) reads this variable to replace the automatic release URL, allowing you to verify error handling without external network dependencies.

### How do I enable memory profiling for performance analysis?

Set `CBM_MEM_PROFILE=1` and specify an output path with `CBM_MEM_PROFILE_OUT=/path/to/output.jsonl`. The profiler writes JSONL records to this file during execution. After the run, process the output using `python scripts/memlab-report.py /path/to/output.jsonl` to generate a human-readable summary of memory allocation patterns.