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

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, 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) 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 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 using strtoul(), converted to bytes, and stored in the global CBMContext struct defined in src/store/store.h. When the store allocates memory, it checks this budget against the internal/cbm/lz4_store.h implementation.

If the budget is exceeded, CBM triggers an LRU eviction routine (implemented in 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:

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

Launch CBM from Python with isolated environment variables:

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, the initialization code retrieves the values using standard C library calls:

/* 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 – Parses the environment variables at start-up and applies defaults.
• src/store/store.h – Holds the global memory-budget field and implements the LRU eviction logic.
• src/pipeline/path_alias.h – Enforces the allowed-root restriction on all file system accesses.
• 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 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 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 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 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.

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