# How to Change the Cache Directory with CBMCACHEDIR in Codebase‑Memory‑MCP

> Learn to change the cache directory for codebase-memory-mcp using the CBMCACHEDIR environment variable. Easily redirect cache storage to your desired location.

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

---

**Set the `CBMCACHEDIR` environment variable to an absolute path before invoking the binary to override the default `./.cbmcache` location and redirect all cache storage to your preferred directory.**

The `codebase-memory-mcp` tool maintains zstd‑compressed indexes and temporary analysis files in a local cache to accelerate subsequent operations. By default, it writes to a hidden `.cbmcache` folder in the current working directory, but production deployments often require relocating this data to faster storage or persistent volumes. The `CBMCACHEDIR` environment variable provides this control, read once during initialization in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go).

## How CBMCACHEDIR is Resolved at Startup

The binary determines the cache root path during initialization by checking `os.Getenv("CBMCACHEDIR")` in the Go entry point. According to the source code in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go), the resolution follows this priority:

1. **Environment variable check**: If `CBMCACHEDIR` is set and points to a valid, writable path, that location becomes the cache root.
2. **Fallback to default**: If the variable is unset, empty, or points to an invalid location, the tool defaults to `./.cbmcache` under the execution directory.
3. **Directory creation**: When the specified path does not exist, the tool automatically creates the directory structure before writing any cache files.

This initialization occurs exactly once at startup, meaning you must export the variable **before** invoking any subcommands like `analyze` or `serve`.

## Configuring CBMCACHEDIR in Different Environments

### Shell Sessions and Scripts

For interactive use or shell scripts, export the variable for the duration of the session:

```bash
export CBMCACHEDIR=/mnt/fast-ssd/cbm_cache
codebase-memory-mcp analyze /path/to/repo

```

For one-off commands without persisting the variable in your environment:

```bash
CBMCACHEDIR=/tmp/cbm_cache codebase-memory-mcp serve

```

### Docker and Containerized Workloads

In containerized environments, set the variable in your Dockerfile or docker-compose configuration to ensure persistent storage across restarts:

```dockerfile
ENV CBMCACHEDIR=/var/lib/cbm/cache
RUN mkdir -p "$CBMCACHEDIR"

```

Mounting a host directory or named volume to this path allows you to preserve caches between container restarts while keeping the storage on high-performance drives.

### CI/CD Pipelines

In continuous integration pipelines, configure the variable at the job level to cache dependencies between runs:

```yaml
variables:
  CBMCACHEDIR: $CI_PROJECT_DIR/.cbm-cache
cache:
  paths:
    - $CI_PROJECT_DIR/.cbm-cache

```

## Low-Level Cache Storage Implementation

Once the path is established, the actual cache operations are handled by the zstd compression layer in [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`internal/cbm/zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.h). These components use the resolved path to locate and store compressed index data.

The C implementation receives the path determined by the Go entry point and handles file I/O operations, ensuring that zstd‑compressed indexes are written to the correct location. If `CBMCACHEDIR` points to a network‑mounted drive or fast SSD, these underlying C functions benefit from the improved I/O performance without requiring code changes.

## Verification and Troubleshooting

To confirm the active cache location, check that the directory exists and contains files after running an analysis:

```bash
ls -la $CBMCACHEDIR

```

If the directory remains empty or the tool reports permission errors, verify that:
- The path is absolute (relative paths may resolve unexpectedly depending on the working directory)
- The process has write permissions to the target directory
- The variable was exported in the same shell session that invokes the binary

## Summary

- **Set `CBMCACHEDIR`** before running the binary to override the default `./.cbmcache` location.
- **Initialization happens once** at startup in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go) via `os.Getenv`.
- **Automatic directory creation** occurs if the specified path does not exist.
- **Underlying storage** uses zstd compression via [`internal/cbm/zstd_store.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.c) and [`internal/cbm/zstd_store.h`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/zstd_store.h).
- **Use absolute paths** for reliable operation in Docker, CI, and production environments.

## Frequently Asked Questions

### What happens if CBMCACHEDIR points to an invalid path?

If the environment variable is set but points to a non-existent or read-only location, the tool falls back to the default `./.cbmcache` directory in the current working directory. The binary validates the path after reading `os.Getenv("CBMCACHEDIR")` during initialization.

### Can I use a relative path with CBMCACHEDIR?

While relative paths are technically accepted, they resolve based on the working directory at execution time, which can lead to inconsistent behavior in Docker containers or CI environments. The source code recommends using absolute paths for predictable cache locations.

### Does the cache directory persist between runs?

Yes, the cache persists on disk indefinitely unless you manually delete it. Setting `CBMCACHEDIR` to a persistent volume or network share allows you to maintain indexes across multiple invocations and system restarts, significantly speeding up subsequent analyses.

### Is CBMCACHEDIR the same as CBM_CACHE_DIR?

No, the implementation specifically checks for `CBMCACHEDIR` (without underscores). Setting `CBM_CACHE_DIR` will not affect the cache location; the variable must be named exactly `CBMCACHEDIR` as implemented in the [`main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/main.go) entry point.