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

> Configure your memory budget with CBM_MEM_BUDGET_MB in Codebase-Memory-MCP. Set the environment variable to easily override automatic RAM calculation for optimal performance.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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):**

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

```

**One-off Execution:**

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

```

**Windows PowerShell:**

```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:

```text
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/cmd/codebase-memory-mcp/main.go)**: Entry point where the server reads environment variables before initializing the indexing pipeline.
- **[`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md)** (line 494): Primary documentation defining the variable behavior and validation rules.
- **[`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.