codebase-memory-mcp Environment Variables: Complete Configuration Reference

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 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 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 (line 113) and 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 (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 (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 (line 87) and 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 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. 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 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 (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

# 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 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.
• 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 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, 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 (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.

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