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

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 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 (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 (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 (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 (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 (lines 109–110), demonstrating its use for temporary test sandboxes.

Practical Configuration Examples

Run a deterministic in-process index for testing:

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

Enable single-threaded mode with crash pinpointing:

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:

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:

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

Redirect logs to a custom location:

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 (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), 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.

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