MCP Performance Tuning: Environment Variables for codebase-memory-mcp

The codebase-memory-mcp server exposes eight environment variables that control memory budgets, worker parallelism, logging verbosity, and storage paths to optimize indexing speed and resource consumption.

The codebase-memory-mcp project by DeusData is a static-binary code-intelligence engine that builds an in-memory knowledge graph during repository indexing. Because this architecture is RAM-first, tuning the available environment variables for performance is essential when running the MCP server on diverse hardware—from high-end workstations to resource-constrained CI containers.

Performance-Critical Environment Variables

The following variables directly impact throughput, latency, and memory usage. Each is defined in the repository’s README.md (lines 16–23) and consumed by the configuration layer in src/mcp/config.c.

CBM_MEM_BUDGET_MB

CBM_MEM_BUDGET_MB overrides the auto-detected in-memory graph budget with an explicit cap in MiB. By default, the budget is calculated as ram_fraction × total_RAM (detected via cgroup or system calls). According to the README (line 22), this value is clamped to detected total RAM and logged as mem.budget.clamped if adjusted.

• Higher values keep more of the graph resident in RAM, reducing disk spills and speeding up indexing.
• Lower values reduce peak memory pressure, which is critical when running alongside sibling processes or within strict cgroup limits.

CBM_WORKERS

CBM_WORKERS sets the parallel-indexing worker count. The default is detected by sysconf(_SC_NPROCESSORS_ONLN) in src/mcp/config.c, but inside containers this often reports host CPUs rather than the cgroup’s effective quota (README line 21).

Valid range is 1–256; invalid values trigger a warning and are ignored. The worker pool implementation in src/pipeline/worker.c uses this value to spawn threads for concurrent file parsing.

CBM_LOG_LEVEL

CBM_LOG_LEVEL controls verbosity with accepted values debug, info, warn, error, none (or numeric equivalents 0–4) as documented in README line 20. Logs are written to stderr; stdout is reserved for MCP JSON-RPC.

Setting this to debug adds substantial I/O and CPU overhead. For production workloads, use warn or error to minimize latency.

CBM_CACHE_DIR

CBM_CACHE_DIR overrides the default database storage directory (~/.cache/codebase-memory-mcp) as noted in README line 17. Because the engine persists the graph to SQLite after indexing, placing this directory on a fast NVMe SSD can significantly improve read/write throughput for large repositories.

CBM_DIAGNOSTICS

CBM_DIAGNOSTICS enables periodic diagnostic snapshots when set to 1 or true (README line 18). When active, the server writes to /tmp/cbm-diagnostics-<pid>.json, which is useful for profiling memory leaks or slowdowns but adds minor I/O cost during heavy indexing.

How Configuration Is Loaded

Environment variables are read at startup via helper functions in src/mcp/config.c. The cbm_get_int_env() function (lines 8–14) wraps getenv() and strtol() to parse numeric values like CBM_WORKERS and CBM_MEM_BUDGET_MB, falling back to system detection when variables are unset or invalid.

// src/mcp/config.c
int cbm_get_int_env(const char* var, int default_val) {
    const char* v = getenv(var);
    if (!v) return default_val;
    char* end;
    long val = strtol(v, &end, 10);
    if (end == v) return default_val;
    return (int)val;
}

The parsed values are then propagated to:

• src/pipeline/worker.c – initializes the worker pool with the specified concurrency.
• src/pipeline/graph.c – enforces the memory budget during graph construction.
• src/main.c – entry point that starts the MCP JSON-RPC server and initializes logging.

Practical Configuration Examples

High-Performance Workstation

Maximize indexing speed on a 32-core machine with 64 GiB RAM:

export CBM_WORKERS=28                 # Leave cores for OS

export CBM_MEM_BUDGET_MB=56000        # ~56 GiB budget (≈87 % of RAM)

export CBM_LOG_LEVEL=warn            # Minimal log overhead

export CBM_CACHE_DIR=/mnt/nvme/cbm-cache # Fast SSD storage

codebase-memory-mcp index_repository repo_path=/abs/path/to/project

Low-Memory Container

Run safely on a 2 GiB container while keeping diagnostics enabled:

export CBM_WORKERS=2
export CBM_MEM_BUDGET_MB=1800         # ~1.8 GiB cap

export CBM_DIAGNOSTICS=1
export CBM_LOG_LEVEL=info

codebase-memory-mcp index_repository repo_path=/abs/path/to/project

Custom Storage Location

Move the persistent cache to an enterprise SSD array:

export CBM_CACHE_DIR=/mnt/raid/cbm-data
codebase-memory-mcp cli list_projects

Summary

• CBM_MEM_BUDGET_MB caps RAM usage for the in-memory graph, trading memory for speed.
• CBM_WORKERS controls parallelism; essential for correct CPU utilization in containerized environments.
• CBM_LOG_LEVEL and CBM_DIAGNOSTICS affect runtime overhead through I/O and processing costs.
• CBM_CACHE_DIR determines storage I/O performance for SQLite persistence.
• Configuration is parsed in src/mcp/config.c via cbm_get_int_env() and applied in src/pipeline/worker.c and src/pipeline/graph.c.

Frequently Asked Questions

What is the default memory budget calculation in MCP?

By default, the budget is calculated as a fraction of total system RAM (ram_fraction × total_RAM) detected via cgroup limits or sysconf. You can override this auto-detection by setting CBM_MEM_BUDGET_MB to a specific MiB value, which is then clamped to the detected total RAM if exceeded.

How does CBM_WORKERS affect indexing performance?

The variable directly sets the size of the parallel worker pool used during repository parsing. More workers increase CPU utilization and indexing speed up to the point where memory pressure or context-switching overhead outweighs the gains. In containers, you should manually set this to match the cgroup’s CPU quota rather than the host’s core count.

Can I disable logging entirely to improve performance?

Yes. Set CBM_LOG_LEVEL to none (or 4) to suppress all stderr logging. This eliminates the I/O and formatting overhead associated with debug or info logs, which is beneficial in latency-sensitive production environments.

Where does MCP store its indexes and configuration by default?

By default, all project indexes and configuration are stored in ~/.cache/codebase-memory-mcp. You can relocate this directory to faster storage using CBM_CACHE_DIR to improve SQLite read/write throughput when reloading large graphs.

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