How to Configure Memory Budget with CBM_MEM_BUDGET_MB in Codebase-Memory-MCP

Set the CBM_MEM_BUDGET_MB environment variable to a positive integer (in MiB) before starting the server to override the automatic RAM-based calculation.

The codebase-memory-mcp server constructs an in-memory graph of your codebase during indexing operations. By default, this graph size is calculated as a fraction of the host's total RAM (ram_fraction × total_RAM), but you can configure a strict memory ceiling using the CBM_MEM_BUDGET_MB environment variable. This override is essential when running inside containers where automatic RAM detection is unreliable or when you need to enforce hard resource limits on shared infrastructure.

How CBM_MEM_BUDGET_MB Works

The CBM_MEM_BUDGET_MB variable acts as a hard ceiling for the in-memory graph allocation, taking precedence over the default automatic calculation. According to the DeusData/codebase-memory-mcp source code, this mechanism is handled during the initialization phase.

Startup Parsing

The variable is read once at process start-up in cmd/codebase-memory-mcp/main.go. The server expects a positive integer representing the budget in MiB (mebibytes). The implementation in internal/**/memory.c immediately overrides the ram_fraction × total_RAM default before the indexing pipeline initializes.

Validation and Clamping

If the supplied value exceeds the actual physical RAM, the system clamps it to the detected total RAM and emits a log entry mem.budget.clamped. Non-numeric, zero, or negative values are rejected with a warning log mem.budget.env.invalid, and the server falls back to the default RAM-based calculation.

Configuring the Memory Budget

You can set the environment variable using your shell's standard syntax before launching the server.

Bash/Zsh (Persistent):

export CBM_MEM_BUDGET_MB=512
codebase-memory-mcp --ui=true

One-off Execution:

CBM_MEM_BUDGET_MB=256 codebase-memory-mcp index_repository '{"repo_path":"/path/to/project"}'

Windows PowerShell:

$env:CBM_MEM_BUDGET_MB = "1024"
codebase-memory-mcp.exe

Verification and Log Monitoring

After startup, verify the effective budget in the server logs. Look for the mem.budget.final entry:

level=info msg=mem.budget.final value=256MiB

If you see mem.budget.clamped, your requested value exceeded available physical RAM. If you see mem.budget.env.invalid, the variable contained an invalid format and was ignored.

Implementation Details

The memory budget logic is implemented across several key files:

• internal/**/memory.c: Core implementation that parses the environment variable and applies clamping logic.
• cmd/codebase-memory-mcp/main.go: Entry point where the server reads environment variables before initializing the indexing pipeline.
• README.md (line 494): Primary documentation defining the variable behavior and validation rules.
• docs/CONFIGURATION.md: General configuration reference including the complete environment variable table.

Summary

• Set CBM_MEM_BUDGET_MB to a positive integer (MiB) before starting the server to override automatic RAM calculations.
• Invalid values trigger warning mem.budget.env.invalid and fall back to defaults.
• Values exceeding physical RAM are clamped with log entry mem.budget.clamped.
• Verify the final budget via the mem.budget.final log entry.
• Implementation resides in internal/**/memory.c and cmd/codebase-memory-mcp/main.go.

Frequently Asked Questions

What happens if I set CBM_MEM_BUDGET_MB higher than my physical RAM?

The value is automatically clamped to the detected total RAM, and the server logs mem.budget.clamped to indicate the adjustment occurred. The system will not attempt to allocate more memory than physically available.

Can I change the memory budget while the server is running?

No. The CBM_MEM_BUDGET_MB variable is read only once at process start-up. Changes require restarting the server to take effect.

Why is my CBM_MEM_BUDGET_MB setting being ignored?

Non-numeric, zero, or negative values are rejected with a mem.budget.env.invalid warning. Ensure you provide a positive integer without units (e.g., 512 not 512MB).

Does CBM_MEM_BUDGET_MB affect disk-based storage or only the in-memory graph?

It applies exclusively to the in-memory graph allocation during indexing. Disk storage and other memory usage are not constrained by this variable.

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