# codebase-memory-mcp Environment Variables: Advanced Configuration with CBMALLOWEDROOT and CBMMEMBUDGETMB

> Configure codebase-memory-mcp with CBMALLOWEDROOT and CBMMEMBUDGETMB environment variables. Restrict file access and cap memory usage for advanced control.

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

---

**Set the `CBMALLOWEDROOT` and `CBMMEMBUDGETMB` environment variables before launching the CLI to restrict file-system access to a specific directory tree and cap memory consumption at a configurable megabyte limit.**

The `codebase-memory-mcp` (CBM) CLI tool reads advanced runtime configuration from environment variables during initialization. According to the source code in [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h), two powerful switches—**CBMALLOWEDROOT** and **CBMMEMBUDGETMB**—allow you to enforce security boundaries and prevent out-of-memory crashes without recompiling the binary.

## Understanding CBMALLOWEDROOT (Allowed File System Root)

**CBMALLOWEDROOT** defines the absolute path that serves as the exclusive boundary for all file operations. When set, the internal *path-alias* manager ([`src/pipeline/path_alias.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/path_alias.h)) resolves every repository scan, cache write, and graph-store operation relative to this root. Any attempt to access files outside this directory tree results in an immediate error, and the offending file is skipped.

If the variable is unset, CBM defaults to the current working directory (`.`). This fallback is applied in [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h) where the code calls `getenv("CBMALLOWEDROOT")` and passes the result to `cbm_set_allowed_root()`.

## Understanding CBMMEMBUDGETMB (Memory Budget Cap)

**CBMMEMBUDGETMB** sets the maximum RAM allocation in megabytes for the internal graph store. The value is parsed in [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h) using `strtoul()`, converted to bytes, and stored in the global `CBMContext` struct defined in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h). When the store allocates memory, it checks this budget against the [`internal/cbm/lz4_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/lz4_store.h) implementation.

If the budget is exceeded, CBM triggers an **LRU eviction** routine (implemented in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h)) to remove least-recently-used nodes rather than consuming additional RAM. The default value is **4096** (4 GB), which protects the host from OOM crashes during large indexing jobs.

## Configuration Examples

You can export these variables in your shell or set them programmatically before spawning the CBM process.

Set the allowed root to `/data/repos` and limit memory to 2 GB:

```bash
export CBMALLOWEDROOT=/data/repos
export CBMMEMBUDGETMB=2048
codebase-memory-mcp index /data/repos

```

Launch CBM from Python with isolated environment variables:

```python
import os
import subprocess

os.environ["CBMALLOWEDROOT"] = "/mnt/projects"
os.environ["CBMMEMBUDGETMB"] = "512"  # 512 MB budget

subprocess.run(["codebase-memory-mcp", "index", "/mnt/projects"])

```

## Implementation Details in Source Code

The environment variables are parsed early in the CLI start-up sequence. In [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h), the initialization code retrieves the values using standard C library calls:

```c
/* Inside src/ui/config.h – environment variable parsing */
const char *root = getenv("CBMALLOWEDROOT");
if (root) {
    cbm_set_allowed_root(root);
}

const char *budget = getenv("CBMMEMBUDGETMB");
if (budget) {
    size_t mb = strtoul(budget, NULL, 10);
    cbm_set_memory_budget(mb * 1024 * 1024);
}

```

Key files involved in enforcing these constraints:

- **[`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h)** – Parses the environment variables at start-up and applies defaults.
- **[`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h)** – Holds the global memory-budget field and implements the LRU eviction logic.
- **[`src/pipeline/path_alias.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/pipeline/path_alias.h)** – Enforces the allowed-root restriction on all file system accesses.
- **[`tests/windows/test_cli_non_ascii_arg.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_cli_non_ascii_arg.py)** – Validates the environment-variable handling in isolated test environments.

## Summary

- **CBMALLOWEDROOT** confines all CBM operations to a specific directory tree, defaulting to the current working directory if unset.
- **CBMMEMBUDGETMB** caps RAM usage in megabytes (default 4096 MB), triggering LRU eviction when exceeded.
- Both variables are read via `getenv()` in [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h) during CLI initialization.
- These settings are essential for running CBM safely in CI pipelines, containers, or multi-tenant servers.

## Frequently Asked Questions

### What happens if I don't set CBMALLOWEDROOT?

CBM defaults to the current working directory (`.`) as the allowed root. All file operations remain restricted to this directory and its subdirectories, but the tool will not prevent access to sibling directories unless you explicitly set a more restrictive root.

### How does CBM enforce the memory budget?

The graph store implementation in [`src/store/store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/store/store.h) checks the allocated memory against the `CBMMEMBUDGETMB` limit before each expansion. When the limit is reached, the store evicts the least-recently-used nodes to free space, ensuring the process does not exceed the configured megabyte cap.

### Can I use relative paths for CBMALLOWEDROOT?

No. The path-alias manager requires an absolute path for the allowed root. If a relative path is provided, the initialization logic in [`src/ui/config.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/ui/config.h) may fail to resolve it correctly, leading to immediate exit with an error code.

### Where are these variables documented in the test suite?

The Windows CLI tests in [`tests/windows/test_cli_non_ascii_arg.py`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/windows/test_cli_non_ascii_arg.py) programmatically set both `CBMALLOWEDROOT` and `CBMMEMBUDGETMB` to temporary directories and low memory values. This ensures the environment-variable parsing logic works correctly across different locales and argument encodings.