How to Override Default Worker Count for Indexing with CBM_WORKERS

Set the CBM_WORKERS environment variable to an integer value before launching the indexer to manually control parallel worker allocation instead of using the auto-detected CPU count.

The codebase-memory-mcp repository indexing system automatically scales worker processes based on the host machine's CPU core count. When you need to override default worker count for indexing with CBM_WORKERS, you gain explicit control over resource consumption, allowing you to limit CPU usage on shared machines or maximize throughput on dedicated CI runners.

How CBM_WORKERS Overrides Auto-Detection

By default, codebase-memory-mcp queries the host system to determine the number of available CPU cores and spawns a corresponding worker pool for repository indexing. This auto-detection logic executes during initialization in pkg/go/cmd/codebase-memory-mcp/main.go, where the environment configuration is loaded.

When you define CBM_WORKERS, the startup sequence reads this variable and uses the specified integer value, completely bypassing the CPU detection heuristics. The resolved worker count is then passed to the internal indexing implementation, which spawns exactly that number of goroutines or threads for parallel processing.

Key characteristics:

• Precedence: Environment variable overrides any internal auto-detection
• Scope: Applies to all indexing operations within the same process lifetime
• Format: Must be a valid integer (e.g., 4, 8, 16)

Configuring CBM_WORKERS Across Operating Systems

You can set the CBM_WORKERS variable temporarily for a single session or persist it across environment configurations.

Unix and macOS (Bash/Zsh)

For the current shell session, export the variable before invoking the command:

export CBM_WORKERS=6
codebase-memory-mcp index /path/to/repo

To apply the setting to a single command without persisting it in the session:

CBM_WORKERS=4 codebase-memory-mcp index /path/to/repo

Windows (PowerShell)

In PowerShell, use the $env: syntax to set the variable for the current session:

$env:CBM_WORKERS = "4"
codebase-memory-mcp.exe index C:\path\to\repo

Or for a single invocation:

$env:CBM_WORKERS="8"; codebase-memory-mcp.exe index C:\path\to\repo

Persistent Configuration with .env Files

For CI pipelines or containerized deployments, store the configuration in a .env file:

CBM_WORKERS=8

Source this file before running the indexer, or ensure your container orchestration platform injects the variable when launching the process from pkg/go/cmd/codebase-memory-mcp/main.go.

Selecting Optimal Worker Count Values

The appropriate value for CBM_WORKERS depends on your execution environment and resource constraints:

• Low-resource environments: Set 1 or 2 workers to prevent CPU saturation on shared development machines or laptops
• Typical development: Use 4 to 8 workers for standard desktop workstations with 4-8 physical cores
• High-throughput CI: Configure 16 or more workers for dedicated CI runners with substantial CPU allocation

According to the source code in docs/CONFIGURATION.md, these values directly determine the size of the worker pool allocated during the indexing phase, affecting both memory consumption and I/O parallelism.

Implementation Details

The override mechanism is implemented in two key locations within the repository:

docs/CONFIGURATION.md documents the variable's behavior, specifying that CBM_WORKERS accepts integer values and takes precedence over automatic core detection.

pkg/go/cmd/codebase-memory-mcp/main.go serves as the entry point where the environment variable is parsed and applied to the indexing subsystem. This file initializes the worker pool that executes the actual repository scanning and memory mapping operations.

The internal indexing implementation consumes this resolved count to spawn the appropriate number of parallel execution units, ensuring the constraint is respected throughout the indexing lifecycle.

Summary

• CBM_WORKERS overrides the automatic CPU core detection in codebase-memory-mcp
• Set the variable to an integer value before launch to control indexing parallelism
• Unix/macOS: Use export CBM_WORKERS=N; Windows: Use $env:CBM_WORKERS="N"
• Typical values range from 1-2 (constrained environments) to 16+ (high-performance CI)
• The setting is processed in pkg/go/cmd/codebase-memory-mcp/main.go and affects all subsequent indexing operations

Frequently Asked Questions

What is the default behavior when CBM_WORKERS is not set?

When CBM_WORKERS is undefined, the system queries the host's CPU core count and spawns a worker pool of corresponding size. This auto-detection ensures out-of-the-box performance optimization without manual configuration.

Does CBM_WORKERS affect repository querying or only indexing?

The variable specifically controls the indexing worker pool—the parallel processes that scan and map repository files into memory. Query operations typically use separate concurrency controls and are not affected by this setting.

How do I configure CBM_WORKERS in a Docker container?

Pass the environment variable using the -e flag when running the container: docker run -e CBM_WORKERS=4 deusdata/codebase-memory-mcp. Alternatively, include it in your docker-compose.yml environment section or Kubernetes pod specification to ensure it is available when the entry point in pkg/go/cmd/codebase-memory-mcp/main.go executes.

What happens if I set CBM_WORKERS to an invalid value?

If CBM_WORKERS is set to a non-integer or negative value, the startup sequence in pkg/go/cmd/codebase-memory-mcp/main.go may fail to parse the environment variable, potentially falling back to the default auto-detection behavior or exiting with a configuration error depending on the specific error handling implemented in that version.

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